Using the docs MCP server

Switchbench publishes a read-only MCP server alongside this site so a coding agent can pull integration context — the pages you are reading now, plus the REST OpenAPI spec — as structured tool calls instead of scraping HTML. It is public, unauthenticated, and serves exactly the content published on the site.

It is a separate server from the Payment Consultant’s MCP endpoint: this one is unauthenticated, serves only the public docs corpus, and is deployed as a Cloudflare Pages Function on the same domain as the site.

Endpoint

POST https://docs.switchbench.com/mcp

Non-production environments use a single-level environment prefix on the host — for example https://test-docs.switchbench.com/mcp. The path and behaviour are identical across environments.

The server speaks MCP over Streamable HTTP and is stateless: every request is an independent JSON-RPC call over POST. There is no session id, no SSE stream (GET returns 405), and no auth header. Any MCP client that can talk to a remote HTTP server works.

Tools

The server registers under the name switchbench-docs and exposes four tools:

Tool	What it returns
list_docs	Every docs page — slug, title, description. The site map, so an agent can pick a page without guessing slugs.
search_docs	Keyword search across all pages. Returns the best matches, each with a short snippet and its slug.
read_doc	The full Markdown body of one page, addressed by the slug from list_docs / search_docs.
get_openapi_spec	The REST OpenAPI 3.1 spec as YAML. Pass an operationId (e.g. postTransactionSalePos) to get just one operation.

Claude Code

Add it with the CLI:

claude mcp add --scope user --transport http switchbench-docs https://docs.switchbench.com/mcp

--scope user registers the server in your user-level config, so it is available in every project on your machine. Without it, claude mcp add defaults to local scope and the server is only visible in the directory you ran the command in.

…or, to share the server with the whole team on this repo rather than just yourself, commit it in .mcp.json at the project root:

{
  "mcpServers": {
    "switchbench-docs": {
      "type": "http",
      "url": "https://docs.switchbench.com/mcp"
    }
  }
}

Run /mcp inside Claude Code to confirm the server connected and its four tools are listed.

Codex

Add it with the CLI:

codex mcp add switchbench-docs --url https://docs.switchbench.com/mcp

This writes an [mcp_servers.switchbench-docs] block into ~/.codex/config.toml. Run codex mcp list (or codex mcp get switchbench-docs) to confirm it registered.

…or add it to ~/.codex/config.toml yourself:

[mcp_servers.switchbench-docs]
url = "https://docs.switchbench.com/mcp"

Older Codex CLI builds launch stdio MCP servers only and have no --url flag. On those, bridge to the HTTP endpoint with mcp-remote:

[mcp_servers.switchbench-docs]
command = "npx"
args = ["-y", "mcp-remote", "https://docs.switchbench.com/mcp"]

Cursor

Add the server to .cursor/mcp.json in the project (or ~/.cursor/mcp.json to enable it everywhere):

{
  "mcpServers": {
    "switchbench-docs": {
      "url": "https://docs.switchbench.com/mcp"
    }
  }
}

Cursor picks the file up on save — check Settings → MCP for a green status and the four tools.

Checking it by hand

The endpoint answers a plain JSON-RPC tools/list over POST. The Accept: application/json, text/event-stream header is required by the Streamable HTTP spec even though this server always replies with JSON:

curl -sS -X POST https://docs.switchbench.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

The response lists the four tools above. A GET to the same URL returns 405 — that is expected; the server is POST-only.