MCP server

The remote MCP server at /mcp. Streamable HTTP, OAuth 2.1 with dynamic client registration or API keys, scopes per area, and approval before anything consequential.

GraphKit is a remote MCP server: everything you can do in the app is an MCP tool that Claude, ChatGPT, Cursor, VS Code, Claude Code and other clients can call. For step-by-step client setup, see Use GraphKit from Claude, ChatGPT and Cursor.

Endpoint and transport

  • URL: https://<app host>/mcp, for example https://app.graphkit.com/mcp. A white-label domain serves the same server on its own host (https://app.agency.com/mcp); tokens are bound to the host that issued them. /api/mcp (Kit's first endpoint) serves the same server for existing clients.
  • Transport: Streamable HTTP. Protocol versions 2026-07-28 (sessionless), 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.
  • POST carries JSON-RPC messages. Send Content-Type: application/json and Accept: application/json, text/event-stream. Responses stream as text/event-stream, so a long call can send progress notifications (_meta.progressToken) before its result.
  • Sessions (protocol versions up to 2025-11-25): initialize returns Mcp-Session-Id. Later requests must send it (400 without, 404 when unknown or expired: start a new session). Sessions are bound to the credential that opened them, end after 24 hours idle or 30 days, and end immediately when the OAuth connection is revoked. DELETE /mcp with the header ends one (204). Any API replica serves any request.
  • Protocol 2026-07-28 is sessionless: no initialize, each request carries _meta (io.modelcontextprotocol/protocolVersion, client capabilities) and the Mcp-Method header; server/discover describes the server.
  • GET answers 405: there is no standalone server-to-client stream.
  • Capabilities: tools (the whole catalogue in one page; nextCursor paging is supported), resources (graphkit://connection, graphkit://approvals/pending), prompts (weekly_report, triage_inbox, plan_campaign), ping (up to 2025-11-25).
  • ?areas=inbox,leads narrows the listed tools to some areas, on top of the scopes.
  • CORS: * without credentials (bearer tokens only), so browser-based inspectors work.

Authentication

Every request needs Authorization: Bearer <token>. A missing or invalid token gets 401 with WWW-Authenticate: Bearer resource_metadata="https://<host>/.well-known/oauth-protected-resource/mcp"; a credential without any MCP scope gets 403 insufficient_scope.

GraphKit is its own authorization server, following the MCP authorization spec (2025-11-25).

EndpointStandard
GET /.well-known/oauth-protected-resource and …/mcpProtected resource metadata (RFC 9728)
GET /.well-known/oauth-authorization-serverAuthorization server metadata (RFC 8414)
POST /oauth/registerDynamic client registration (RFC 7591)
GET /oauth/authorizeAuthorization code, PKCE S256 only (RFC 7636), resource indicator (RFC 8707)
POST /oauth/tokenauthorization_code and refresh_token
POST /oauth/revokeToken revocation (RFC 7009)
  • Clients: registered dynamically (public clients with token_endpoint_auth_method: none, or confidential with client_secret_basic / client_secret_post), or identified by a client ID metadata document (the client_id is an https URL; fetched with an SSRF-guarded client and refreshed daily). Redirect URIs: https, http on loopback only (any port, RFC 8252), or private-use schemes such as cursor://; never fragments or script schemes.
  • Consent: /oauth/authorize validates the request and sends the browser to /oauth/consent?request=<id> in the SPA, on the same host, so it carries the white-label brand. The person signs in if needed, then picks the workspace, read-only or read-and-write, and optionally limits the areas. The SPA calls GET and POST /api/app/me/oauth-requests/{id}. Support sessions cannot approve. Requests last 10 minutes and are single use.
  • Tokens: opaque, stored as SHA-256. Access tokens (gkmcp_at_…) last 1 hour. Refresh tokens (gkmcp_rt_…) last 30 days and rotate on every use; presenting a spent refresh token revokes the whole connection. A replayed authorization code revokes the connection too (RFC 6749 §4.1.2). The iss parameter is returned on the redirect (RFC 9207).
  • Connected apps: each consent is a grant listed in Account → Connected apps and Settings → MCP (GET /api/app/me/connected-apps); DELETE /api/app/me/connected-apps/{id} revokes its tokens and sessions immediately. Workspace admins (team.manage) see every connection in the workspace with the person it acts as (GET /api/app/workspaces/{workspaceId}/mcp-connections) and can revoke any of them (DELETE …/mcp-connections/{id}), which ends its tokens and sessions immediately. Connecting, disconnecting and revoking are audited (mcp.app.connected, mcp.app.disconnected, mcp.app.revoked).

API keys

Workspace API keys (gk_live_…, Settings → MCP → Create MCP key or Settings → API keys) with an MCP scope. A key acts as the person who created it, inside the key's workspace.

Scopes

ScopeAllows
mcp:readevery read tool
mcp:writeevery tool (write implies read)
mcp:<area>:readthe read tools of one area
mcp:<area>:writeevery tool of one area
kit:read, kit:writeolder names of mcp:read and mcp:write

Areas: accounts, leads, campaigns, inbox, analytics, integrations, workspace, billing, autopilot, infrastructure. The approval tools (get_approval, list_pending_approvals) are listed for every connection that can write anywhere. A tool also needs the person's role (built-in or custom, see Roles and permissions) to hold its permission; tools the role cannot use are not listed, and a suspended person's connections stop working. Roles, the security policy, members' sessions and ownership are never tools.

Tools

The tools are generated from the app API's OpenAPI description: their input schemas are the API's own request schemas, so new fields and new read endpoints appear automatically.

  • Coverage: every app API operation is a tool, or is left out on purpose for the reasons below.
  • Exempt by design: sign-in, the person's own security settings and connected apps (/api/app/auth, /api/app/me), browser OAuth flows, invitation links, endpoints that return one-time secrets (new API keys, webhook and lead hook secrets, report share links, mailbox credentials, domain transfer codes, the Warmbly sign-in link), binary uploads and downloads, live event streams, Kit's own chat panel, deciding approvals, Kit's approval policy, the sign-in security policy, and listing or revoking the workspace's connected apps. Platform admin routes are never tools.
  • Names and titles: snake_case, verb first (search_conversations, pick_variant_winner), with a title (Search the inbox).
  • Annotations: readOnlyHint, destructiveHint (deletes, suppressions, archive), idempotentHint (reads, PUT, PATCH, DELETE), openWorldHint (LinkedIn, email platforms, CRMs, webhooks, Slack, Stripe, registrars). _meta carries com.graphkit/area and, for consequential tools, com.graphkit/approval.
  • Results: the app API's JSON response as text (cut at 60,000 characters with a note). Errors are tool results with isError: true and the HTTP status.

Safety

  • Tenancy: a call is an in-process request to the app's own route as the connected person, with the same tenancy guards, permission checks, 2FA requirement and validation as the web app. The person's standing is re-resolved on every request; there is never a platform-admin override. Foreign ids read as not found.
  • Approvals: consequential tools use Kit's approval classes (send_message, campaign_state, enrollment, import, destructive, team, developer, billing). Over MCP nothing is auto-approved, whatever the workspace's Kit settings. Every change to what the organization pays is a billing tool that always asks: change_seat_quantity, cancel_subscription, resume_subscription, add_autopilot, remove_autopilot, add_warmbly, change_warmbly_plan, remove_warmbly (and the checkout and billing portal links). The tool returns {"status":"awaiting_approval","approvalId","approvalUrl","title","summary"}. A person approves or rejects it in Kit → Approvals; it then runs as that person. The client polls get_approval, which reports only the caller's own requests. A connected app cannot approve anything: deciding approvals is not a tool.
  • Secrets: endpoints that create secrets are not tools, and any secret-looking field (secret, apiKey, password, token, webhookUrl, …) left in a response is replaced before the client sees it.
  • Rate limits: 120 requests per minute per token or key (429 with Retry-After); registration and the token endpoint are limited per IP.
  • Audit: every change is written to the audit log with actor_type = mcp, the person's id and the client's name ("MCP client Claude on behalf of Ada"); the audit log API returns it as actorClient.
  • Untrusted content: the server instructions tell clients that message text, lead data and files are data, not instructions.

On this page