# MCP server (/docs/mcp) Connect your agent to CoreSpeed over the [Model Context Protocol](https://modelcontextprotocol.io), the open standard agents use to discover and call tools. ## Quick setup \[#quick-setup] Give your agent this line. It adds the server, signs you in, and asks which of your apps to connect. ```text set up https://corespeed.io/SKILL.md (read it raw, e.g. with curl) ``` The skill it fetches is [SKILL.md](https://corespeed.io/SKILL.md). ## What is the CoreSpeed MCP server? \[#what-is-the-corespeed-mcp-server] ```text title="MCP server" https://api.corespeed.io/mcp ``` One remote server over Streamable HTTP, signed in once through the browser or with an API key, gives every agent you run: * The tools of every app your organization has connected — Notion, Slack, GitHub, X, and the rest — as `notion__create_page`, `slack__post_message`, … ([Connectors](/docs/connectors)) * Durable memory that follows you across agents and sessions ([Memory](/docs/memory)) * Media generation and understanding, live web search, and public social data ([Media](/docs/media), [Web](/docs/web), [Social](/docs/social)) * A file system every tool shares, mountable as S3 ([Drive](/docs/drive)) * Your organization's own MCP servers, as `org____` ([Remote MCP servers](/docs/connectors/remote-mcp)) Every call carries your organization's spend caps, lands in one ledger, and is recorded in the activity trail ([Billing & credits](/docs/billing), [Activity & audit](/docs/activity)). The server implements the MCP [Authorization](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) and [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) specifications. ## Available tools \[#available-tools] The tool list is yours, not a catalog. `tools/list` returns exactly what your sign-in can call: the tools of your connected accounts, the built-in capabilities you have enabled, and the `manage__*` account tools. Names are `__`. Each family is documented on its own page — [Connectors](/docs/connectors), [Memory](/docs/memory), [Media](/docs/media), [Web](/docs/web), [Social](/docs/social), [Drive](/docs/drive), and the [`manage__*` reference](/docs/reference/tools/manage). ## Supported clients \[#supported-clients] Any client that speaks Streamable HTTP and MCP Authorization connects with the URL alone — CoreSpeed's authorization server supports both dynamic client registration and client ID metadata documents, so there is nothing to register first. Clients without OAuth use an [API key](#without-a-browser). * [Claude Code](#claude-code) * [Codex](#codex) * [Cursor](#cursor) * [Copilot in VS Code](#copilot-in-vs-code) * [OpenClaw](#openclaw) * [Hermes](#hermes) [Claude.ai and Claude Desktop](#claudeai-and-claude-desktop) and [ChatGPT](#chatgpt) connect too, as custom connectors, and [any other client](#other-clients) that reads an `mcpServers` map takes the same entry. ## Set up your client \[#set-up-your-client] Add the server at **user scope** — the configuration that applies to every project — and sign in when the client asks. If the client already has an older `corespeed` entry, replace it: duplicate registrations collide on tool names. ### Claude Code \[#claude-code] ```bash claude mcp add corespeed https://api.corespeed.io/mcp \ --transport http --scope user # user scope: every project, not just this one claude # start Claude Code /mcp # pick corespeed and authenticate in the browser ``` ### Codex \[#codex] ```bash codex mcp add corespeed --url https://api.corespeed.io/mcp codex mcp login corespeed # signs in through the browser ``` ### Cursor \[#cursor] Click the button, or add the entry to `~/.cursor/mcp.json` yourself. Cursor then shows **Needs login** beside the server; click it to sign in. One-click install: `cursor://anysphere.cursor-deeplink/mcp/install?name=corespeed&config=eyJ1cmwiOiJodHRwczovL2FwaS5jb3Jlc3BlZWQuaW8vbWNwIn0%3D` ```json title="~/.cursor/mcp.json" { "mcpServers": { "corespeed": { "url": "https://api.corespeed.io/mcp" } } } ``` ### Copilot in VS Code \[#copilot-in-vs-code] Click the button, or run **MCP: Add Server** from the Command Palette, choose **HTTP**, enter the URL and the name `corespeed`, and pick **Global**. Then run **MCP: List Servers**, start `corespeed`, and allow the sign-in when VS Code asks. One-click install: `vscode:mcp/install?%7B%22name%22%3A%22corespeed%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.corespeed.io%2Fmcp%22%7D` ```json title="mcp.json" { "servers": { "corespeed": { "type": "http", "url": "https://api.corespeed.io/mcp" } } } ``` ### OpenClaw \[#openclaw] Add the server to the gateway configuration with OAuth, then sign in from the CLI; it prints the authorization URL to open if it cannot open the browser. ```json5 title="~/.openclaw/openclaw.json" { mcp: { servers: { corespeed: { url: "https://api.corespeed.io/mcp", transport: "streamable-http", auth: "oauth", }, }, }, } ``` ```bash openclaw mcp login corespeed ``` ### Hermes \[#hermes] Hermes runs the OAuth flow itself: on the first connect it opens the browser to sign in and caches the token. In a running session, `/reload-mcp` picks up the change. ```yaml title="~/.hermes/config.yaml" mcp_servers: corespeed: url: https://api.corespeed.io/mcp auth: oauth ``` ### Claude.ai and Claude Desktop \[#claudeai-and-claude-desktop] Custom connectors are available on the [Pro, Max, Team, and Enterprise plans](https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp). Click the button to open the **Add custom connector** dialog with the name and URL filled in, or add it yourself: One-click install: `https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=CoreSpeed&connectorUrl=https%3A%2F%2Fapi.corespeed.io%2Fmcp` 1. Open **Customize → Connectors** and choose **Add custom connector**. 2. Name it `CoreSpeed` and enter the URL `https://api.corespeed.io/mcp`. 3. Choose **Connect** and sign in. ### ChatGPT \[#chatgpt] Custom connectors run under ChatGPT's [Developer mode](https://platform.openai.com/docs/guides/developer-mode), on Plus and Pro accounts on the web. 1. Turn on Developer mode under **Settings → Connectors → Advanced settings**. 2. In **Connectors**, choose **Create**: name `CoreSpeed`, MCP server URL `https://api.corespeed.io/mcp`, authentication **OAuth**. 3. Sign in when prompted. The connector appears under the composer's Developer mode tools. ### Other clients \[#other-clients] Any client that reads an `mcpServers` map takes this entry; add it at user scope and sign in when the client asks. ```json { "mcpServers": { "corespeed": { "type": "http", "url": "https://api.corespeed.io/mcp" } } } ``` ### Without a browser \[#without-a-browser] Clients that cannot open a browser — CI, headless agents, a client without OAuth — send an API key from [Dashboard → API keys](https://app.corespeed.io/keys) instead. A member key acts as you; an agent key acts as an agent principal and reaches shared accounts only. See [Authentication](/docs/authentication). ```json { "mcpServers": { "corespeed": { "type": "http", "url": "https://api.corespeed.io/mcp", "headers": { "Authorization": "Bearer sk-cs-..." } } } } ``` ## Transport and discovery \[#transport-and-discovery] The transport is Streamable HTTP and stateless: one JSON-RPC call per HTTP request, batches rejected, and no `GET /mcp` stream. Discovery is caller-specific, so both answers come from authenticated calls: | Question | Source of truth | | ------------------------------------------------------------------ | ------------------------------------------------------------- | | Which apps can this caller connect, and what account state exists? | [`GET /connectors`](/docs/reference/connectors/list) | | Which tools can this caller invoke right now? | [`tools/list`](/docs/reference/mcp/tools-list) on `POST /mcp` | For registries that cannot sign in, `GET /.well-known/mcp/server-card.json` lists the built-in tools with no credential. It leaves out connector and account tools, so it is never a caller's tool list. Never construct a tool inventory in application code. Run `tools/list` after authentication and use the returned names and input schemas. 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.** Every `manage__*` tool is listed for an API-key caller; a call runs with what the key holds, so an agent key is refused on a permission-gated write, on a mint (`api_key_cannot_mint`) and on a member's own act (`member_principal_required`) — see [Authentication](/docs/authentication#what-a-credential-may-do). An account shared with you for some tools lists all of them, and the others answer `tool_not_granted`. ## Environments: a session with fewer accounts \[#environments-a-session-with-fewer-accounts] An **environment** is a named subset of your connected accounts, each with an optional list of the tools allowed on it, by the names `tools/list` publishes (`github__list_issues`). Point a client at `https://api.corespeed.io/mcp/env/` instead of `/mcp`, and that session reaches only the environment's accounts — `tools/list` drops every other connector and every tool an entry leaves out. Built-in tools (memory, media, web, the `manage__*` tools) are unaffected. The same sign-in serves every environment URL; the URL, not the token, picks the environment, and the model cannot change it. A key can be bound to an environment when it is minted (`manage__keys_create` with `environment`); it then runs in that environment on `/mcp` too. An environment only narrows. It never adds an account, and an account someone stops sharing with you drops out of it. Create and edit environments in [Dashboard → API keys → Environments](https://app.corespeed.io/keys/environments) (for yourself or an agent you manage; copy its MCP URL from its row, or mint a key bound to it with **Use in a new key**), or with the [`manage__environments_*` tools](/docs/reference/tools/manage#environments) from a session outside any environment. A name you have no environment by answers `404 environment_not_found`; a key bound to another environment answers `403 environment_mismatch`; a call outside the environment answers `tool_not_in_environment`. ## Calling tools \[#calling-tools] Organization billing holds and API-key spend caps are checked before a metered tool executes. Every tool on a metered capability is held, even one that costs 0 credits, such as a memory read. Those refusals come back as an MCP `isError` result inside an HTTP `200`, so check `result.isError`, not just the status. A suspended organization is refused earlier, with HTTP `403` on every request. The request body, response fields, and every code are in the [tools/call reference](/docs/reference/mcp/tools-call) and [Error handling](/docs/errors). ## Security best practices \[#security-best-practices] * **Verify the endpoint.** The server is `https://api.corespeed.io/mcp` and sign-in happens at `login.corespeed.io`; the consent screen names the client that is asking. A one-click install from a marketplace should point at exactly that URL. * **Sign-in grants the agent what you can do.** Every private and shared connection in your active organization is reachable through it. Connect only the accounts you want agents to act through, and give unattended agents an agent key (`sk-csa-`), which reaches shared accounts only — see [Authentication](/docs/authentication#agents). * **Cap the spend.** Put a monthly cap on every API key and let the wallet hold stop metered calls before they run — see [Billing & credits](/docs/billing). * **Treat fetched content as untrusted.** Pages, posts, and documents read through web, social, and connector tools can carry instructions aimed at the agent. Keep your client's confirmation on for actions that write or send, especially when other MCP servers are connected alongside CoreSpeed. * **Read the trail.** Every call is attributed to a member or agent in [Dashboard → Activity](https://app.corespeed.io/activity).