MCP

MCP (Model Context Protocol) lets an AI client use Benchmark as a tool. The Benchmark MCP server is at:

https://api.benchmark.app/mcp

It offers the same stored reads, refreshes, collections, and subscription listing as the REST API.

Before you connect

Create a Benchmark account at benchmark.app.
Create a workspace, or accept an invite to one. If your account has no workspace, the server returns 403 FORBIDDEN.
Start a plan for the workspace. Paid operations need credits, and the dashboard MCP page shows the setup steps only when the workspace has a plan.

Authenticate

There are two ways to sign in to the MCP server.

Sign in with your Benchmark account (OAuth). Apps such as Claude and Cursor open a Benchmark sign-in page. After you sign in, the app acts for your workspace.
API key. Scripts and servers can send a Benchmark API key in the authorization header, after the word Bearer. Treat the key like a password. Do not put it in a config file that you share.

Open the dashboard MCP settings to copy the endpoint, control workspace access, and see connected clients and activity.

Connect a client

Find your client below. After you add the server, the client asks you to sign in to Benchmark.

Claude Code

Add the remote HTTP server from your terminal:

claude mcp add --transport http benchmark https://api.benchmark.app/mcp

Then start Claude Code, run /mcp, select benchmark, and sign in.

Codex

Add the server:

codex mcp add benchmark --url https://api.benchmark.app/mcp

Then sign in:

codex mcp login benchmark

Cursor

Add this server to your mcp.json, then connect benchmark from Cursor’s MCP settings:

{
  "mcpServers": {
    "benchmark": {
      "url": "https://api.benchmark.app/mcp"
    }
  }
}

Claude

In Claude, open Customize > Connectors, select Add custom connector, and enter https://api.benchmark.app/mcp. Complete the Benchmark sign-in flow when Claude opens it.

ChatGPT

Enable developer mode in ChatGPT. Under Settings > Apps, create a custom app with https://api.benchmark.app/mcp, then complete the Benchmark sign-in flow.

Grok

Open grok.com/connectors. Choose New connector > Custom, paste https://api.benchmark.app/mcp, then sign in to Benchmark when Grok asks.

Tools

The server has four tools. mutate appears only when the workspace allows writes.

Tool	What it does
`whoami`	Shows your organization, how you signed in, the server URL, and if writes are on. When you sign in with OAuth, it also shows your role.
`list_operations`	Lists every operation. Give it one operation name to see that operation’s input, result, and errors, plus an example call.
`query`	Runs a stored read. It returns the same JSON as the REST API.
`mutate`	Asks for a refresh. It appears only when write access is on.

Use the operation catalog

Call list_operations first. Each operation description lists its input fields and shows an example call for query or mutate.

This short example reads a profile, follows the suggested refresh, and polls the collection:

Client → whoami
Benchmark → {"organization":{"id":"00000000-0000-4000-8000-000000000000","name":"Example","status":"active"},"credential":"user","role":"admin","mutationsEnabled":true,"resource":"https://api.benchmark.app/mcp"}

Client → list_operations {"operation":"readProfilesBasic"}
Benchmark → ## Parameters
            target: object (required)
            ...
            Run with the query tool: {"operation":"readProfilesBasic","input":{...}}

Client → query {"operation":"readProfilesBasic","input":{"target":{"platform":"youtube","reference":"@mkbhd"}}}
Benchmark → {"code":"NOT_FOUND","requestId":"90000000-0000-4000-8000-000000000009","message":"The requested entity was not found.","nextOperation":{"tool":"mutate","operation":"refreshProfilesBasic","input":{"target":{"platform":"youtube","reference":"@mkbhd"}}}}

Client → mutate {"operation":"refreshProfilesBasic","input":{"target":{"platform":"youtube","reference":"@mkbhd"}}}
Benchmark → {"collection":{"id":"00000000-0000-4000-8000-000000000001","status":"queued",...}}

Client → query {"operation":"getCollection","input":{"collectionId":"00000000-0000-4000-8000-000000000001"}}
Benchmark → {"collection":{"id":"00000000-0000-4000-8000-000000000001","status":"complete",...},"result":{...}}

query takes an optional fields input. When the result has a data object, fields keeps only the top-level keys that you name. Collection results are not changed.

listSubscriptions is the only subscription operation. There is no create or deactivate operation yet, in MCP or in REST.

Manage MCP access

The dashboard MCP settings page has four sections:

Connect shows the setup commands and the endpoint.
Access lets an admin choose Off, Read-only, or Read and write. Read-only hides mutate. Off rejects every MCP connection for the workspace.
Connected clients lists each client. It shows who used it (a member or an API key), the first and last use, and the request count. Each API key is its own client with a 16-character ID. An admin can disconnect any client. Disconnecting an API-key client affects only that key. A member can disconnect their own signed-in clients.
Activity shows recent requests, and usage by tool and by operation.

Billing

Stored reads that succeed and refreshes that complete spend workspace credits. MCP uses the same prices and billing rules as the REST API. These are free: list_operations, whoami, failed operations, and listSubscriptions.

Errors

Errors arrive in one of two ways.

HTTP errors. Sign-in, access mode, origin, revoked clients, rate limits, and credit checks fail the whole HTTP request. The body uses the same error format as the REST API. A 401 response has a WWW-Authenticate header. MCP clients use it to start sign-in.
Tool errors. A failed operation comes back as a tool result.

Do not send an Origin header. The server rejects any request that has one with 403 FORBIDDEN.

HTTP responses

Status	Codes	Response
400	`INVALID_REQUEST`	Send one valid JSON-RPC request.
401	`UNAUTHORIZED`	Sign in again or replace the invalid API key.
402	`INSUFFICIENT_CREDITS`, `USAGE_CAPPED`	Start a plan, add credits, or change the spend cap.
403	`FORBIDDEN`	Check access mode, workspace membership, and revocation. Remove any `Origin` header.
404	`NOT_FOUND`	Check the URL. The MCP endpoint is `https://api.benchmark.app/mcp`.
429	`RATE_LIMIT_EXCEEDED`	Retry with backoff.
503	`SERVICE_UNAVAILABLE`	Retry later.

Tool error codes

Tool errors are MCP results with isError: true. Their text is compact JSON with code, requestId, message, and optional fields or nextOperation.

HTTP equivalent	Codes	Response
400	`INVALID_REQUEST`, `INVALID_IDENTIFIER`	Correct the named fields or choose an operation from `list_operations`.
402	`INSUFFICIENT_CREDITS`, `USAGE_CAPPED`	Start a plan, add credits, or change the monthly spend cap in the dashboard.
403	`FORBIDDEN`, `DATA_NOT_PUBLIC`	Check organization membership, MCP access mode, and data permissions.
404	`NOT_FOUND`, `COLLECTION_NOT_FOUND`, `SUBSCRIPTION_NOT_FOUND`	Follow `nextOperation` when present, or verify the resource ID.
409	`CONFLICT`, `COLLECTION_ALREADY_DELIVERED`	Read the current state before you repeat the change. A collection returns its data one time.
422	`UNSUPPORTED_OPERATION`	Select an operation supported for the requested entity.
500	`INTERNAL_ERROR`	Retry once, then report the request ID if the error continues.
503	`CONTENT_UNAVAILABLE`, `SERVICE_UNAVAILABLE`	Retry service failures later; choose another target when content is unavailable.
504	`REQUEST_TIMEOUT`	Retry with backoff.

Next steps

Read the API reference for operation inputs, response shapes, collection states, and the complete error meanings.