Connect MCP clients

Your API's MCP server reaches agents two ways: as a local process the client spawns (the server inside your package, over stdio) or as a remote URL (the hosted endpoint, or a server you deployed with --http or on Cloudflare). This guide shows both for each client. Replace acme with your package's bin.

Fastest: let the CLI do it

The generated CLI writes the client configuration for you and never puts a token in the file. Run it from the directory of the project that should see the server:

acme login                  # once; the MCP server shares these credentials
acme mcp --claude           # ./.mcp.json
acme mcp --cursor           # ./.cursor/mcp.json
acme mcp --claude-desktop   # Claude Desktop's config file

For the hosted endpoint, add --url:

acme mcp --url https://typeship.dev/mcp/<slug> --claude

Add --read-only to either form for a server that cannot write: the local entry gets the --read-only flag, the hosted URL gets /readonly. See Read-only and narrower servers.

Claude Desktop takes remote servers as connectors in the app (Settings, Connectors, Add custom connector), not through its config file, so --claude-desktop --url prints that instruction instead of writing an entry.

Clients must speak MCP 2026-07-28 (per-request _meta, server/discover); Claude Code and Claude Desktop do. Cursor's MCP client is still on the initialize handshake as of Cursor 3.2 and does not connect; see the protocol notes.

Build the package first (npm install && npm run build) so dist/mcp.js exists. Existing servers in the file are preserved.

Manual configuration

{
  "mcpServers": {
    "acme": {
      "command": "node",
      "args": ["/abs/path/acme/dist/mcp.js"]
    }
  }
}

{
  "mcpServers": {
    "acme": {
      "type": "http",
      "url": "https://typeship.dev/mcp/<slug>"
    }
  }
}

Credentials

A local server resolves credentials like the CLI: environment variables (ACME_TOKEN), then whatever acme login saved. A remote server forwards each caller's Authorization header to your API. When your spec declares OAuth2, clients that support it discover the authorization server through the standard challenge. See OAuth discovery.

Check it works

Ask the agent to list the tools, or call one directly:

Use the acme server to list my accounts.

Every server also answers search_docs and read_docs, so "how does pagination work in the Acme API?" is answerable in the session when a docs site is configured.