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 examplehttps://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/jsonandAccept: application/json, text/event-stream. Responses stream astext/event-stream, so a long call can send progress notifications (_meta.progressToken) before its result. - Sessions (protocol versions up to 2025-11-25):
initializereturnsMcp-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 /mcpwith 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 theMcp-Methodheader;server/discoverdescribes the server. - GET answers 405: there is no standalone server-to-client stream.
- Capabilities:
tools(the whole catalogue in one page;nextCursorpaging is supported),resources(graphkit://connection,graphkit://approvals/pending),prompts(weekly_report,triage_inbox,plan_campaign),ping(up to 2025-11-25). ?areas=inbox,leadsnarrows 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.
OAuth 2.1 (recommended)
GraphKit is its own authorization server, following the MCP authorization spec (2025-11-25).
| Endpoint | Standard |
|---|---|
GET /.well-known/oauth-protected-resource and …/mcp | Protected resource metadata (RFC 9728) |
GET /.well-known/oauth-authorization-server | Authorization server metadata (RFC 8414) |
POST /oauth/register | Dynamic client registration (RFC 7591) |
GET /oauth/authorize | Authorization code, PKCE S256 only (RFC 7636), resource indicator (RFC 8707) |
POST /oauth/token | authorization_code and refresh_token |
POST /oauth/revoke | Token revocation (RFC 7009) |
- Clients: registered dynamically (public clients with
token_endpoint_auth_method: none, or confidential withclient_secret_basic/client_secret_post), or identified by a client ID metadata document (theclient_idis 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 ascursor://; never fragments or script schemes. - Consent:
/oauth/authorizevalidates 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 callsGETandPOST /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). Theissparameter 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
| Scope | Allows |
|---|---|
mcp:read | every read tool |
mcp:write | every tool (write implies read) |
mcp:<area>:read | the read tools of one area |
mcp:<area>:write | every tool of one area |
kit:read, kit:write | older 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)._metacarriescom.graphkit/areaand, 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: trueand 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 abillingtool 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 pollsget_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 asactorClient. - Untrusted content: the server instructions tell clients that message text, lead data and files are data, not instructions.