MCP endpoint

Discover and invoke the caller-specific CoreSpeed tool surface through one authenticated Streamable HTTP endpoint.

Every connector and built-in tool is served through one MCP endpoint:

Production MCPPOST https://api.corespeed.io/mcpAuthenticate with browser sign-in, a CoreSpeed key, or a user session JWT

Connect with OAuth (browser sign-in)

Agents such as Claude Code and Cursor connect with only the URL (Copilot in VS Code uses its own servers shape — see Getting started): on the first call they receive a 401 that advertises CoreSpeed's protected-resource metadata, which names the authorization server; the client registers itself, opens your browser to sign in, and stores the token. Nothing to copy or rotate.

MCP configuration (OAuth)
{
  "mcpServers": {
    "corespeed": {
      "type": "http",
      "url": "https://api.corespeed.io/mcp"
    }
  }
}
401 challenge

POST /mcp with no token returns a WWW-Authenticate header pointing at the RFC 9728 protected-resource metadata

discover authorization server
browser sign-in

the client registers with the authorization server (via CIMD or DCR where enabled) and you approve access in the browser

token issued
authenticated

the client calls /mcp with the issued token; organization and budget resolve as usual

the client discovers and completes OAuth 2.1 + PKCE on its own

The gateway issues no tokens itself — the authorization server owns registration, consent, and issuance. The token is scoped to this /mcp resource (RFC 8707), so it cannot be replayed against another server.

Connect with an API key

Headless and CI clients send a long-lived CoreSpeed key or a user session JWT in the Authorization header instead of running the browser flow:

MCP configuration (API key)
{
  "mcpServers": {
    "corespeed": {
      "type": "http",
      "url": "https://api.corespeed.io/mcp",
      "headers": {
        "Authorization": "Bearer sk-cs-..."
      }
    }
  }
}

The transport is Streamable HTTP and stateless. Send one JSON-RPC call per HTTP request; JSON-RPC batches are rejected.

Tool identity

Wire tool names use <capability-id>__<operation> with a double underscore. Examples include memory__remember and memory__search_memory; connected software follows the same convention.

Two discovery questions

Discovery is caller-specific, so both answers come from authenticated calls:

QuestionSource of truth
Which software can this caller connect, and what account state exists?GET /connectors
Which tools can this caller invoke right now?tools/list on POST /mcp

Never construct a tool inventory in application code. Run tools/list after authentication and use the returned names and input schemas — the result is already filtered for the caller's connected accounts and enabled built-ins. Read it with three caveats:

  • Absence is a decision, not a bug. If a tool is missing, this caller cannot invoke it: the capability is off, or the account is not connected.
  • Presence is not health. A connector account in needs_reauth still contributes tools; those calls fail until the account is reauthorized. Check account status in GET /connectors when a visible tool keeps failing.
  • Presence is not permission. The session-gated manage__* tools are listed for an API-key caller but answer jwt_session_required — see Authentication.

Call a tool

Organization billing holds, suspensions, and API-key spend caps are checked before a metered tool executes. These failures can be returned as an MCP isError result inside an HTTP 200 response — the HTTP status stays 200, so check result.isError too.

The request body, response fields, and every status code live in the tools/call reference, with samples in curl, TypeScript, Python, and Go.

On this page

Connect with OAuth (browser sign-in)Connect with an API keyTool identityTwo discovery questionsCall a tool