Skip to main content

MCP Quickstart

Shuuka exposes itself to AI assistants through the Model Context Protocol. Any MCP-compatible client — Claude Desktop, ChatGPT Desktop, Cursor, your own — can authenticate against Shuuka and call typed, audited tools on a user's account.

This page gets you connected in under five minutes.

What you get​

  • a large catalog of typed tools across three trust tiers: public reads, owner actions, manager workflows.
  • OAuth 2.1 with Dynamic Client Registration — no platform whitelisting, no manual key exchange.
  • Per-tool consent, audit log, one-click revoke — all surfaced in the user's Shuuka settings.
  • Per-tier rate limits: Free 500 calls/month, Pro 10,000, Enterprise 100,000.
  • Webhooks for state-change events (link clicks, fake reports, verifications).

Endpoints​

PurposeURL
MCP JSON-RPC dispatcherhttps://mcp.shuuka.com/
OAuth Authorization Serverhttps://mcp.shuuka.com/.well-known/oauth-authorization-server
Protected Resource metadatahttps://mcp.shuuka.com/.well-known/oauth-protected-resource
MCP server manifesthttps://mcp.shuuka.com/.well-known/mcp
DCR registrationPOST https://mcp.shuuka.com/oauth/register
Token endpointPOST https://mcp.shuuka.com/oauth/token
Token revocationPOST https://mcp.shuuka.com/oauth/revoke
Health probeGET https://mcp.shuuka.com/health

The MCP host is mcp.shuuka.com in production. In local development it also mounts under https://api.shuuka.local/mcp-dev for convenience.

Connect from a hosted MCP client​

Most desktop MCP clients (Claude Desktop, ChatGPT, Cursor) accept a remote server URL and run the OAuth flow for you.

  1. Add a new remote MCP server in your client.
  2. Paste https://mcp.shuuka.com/ as the server URL.
  3. Discovery is automatic via .well-known/oauth-authorization-server.
  4. The client registers itself via DCR, opens the consent screen in your browser, and stores the resulting access token.
  5. Approve the scopes you want the client to have. You will see them on a Shuuka-branded consent page.

You're done. Ask the assistant something like:

What's my Shuuka identity score this month?

The client maps that to the get_identity_score tool, calls it, and answers from real data.

Connect a custom client​

If you're building your own MCP client, the full flow is:

  1. Discover — fetch https://mcp.shuuka.com/.well-known/oauth-authorization-server.
  2. Register — POST /oauth/register with your client metadata. Receive a client_id (and client_secret for confidential clients).
  3. Authorize — redirect the user to the authorization_endpoint with response_type=code, your client_id, redirect_uri, requested scope, and a PKCE challenge.
  4. Token — exchange the authorization code at /oauth/token with the PKCE verifier.
  5. Call tools — POST JSON-RPC requests to https://mcp.shuuka.com/ with Authorization: Bearer <access_token>.

See Authentication for the details, including PKCE, scopes, and step-up auth.

Health check​

Verify the server is reachable:

curl https://mcp.shuuka.com/health

Returns:

{
  "ok": true,
  "server": "Shuuka MCP",
  "version": "1.0.0",
  "protocol": "2025-06-18",
  "docs": "https://shuuka.com/docs/mcp/quickstart"
}

Next​