MCP

Bring public content research into your AI workflow. Benchmark’s MCP server lets supported clients use the same research views as the REST API. Plans with write access can also request refreshes. The server is at:

https://api.benchmark.app/mcp

Connect a client

Copy the setup prompt below into your AI client, or choose the manual steps for your client. The setup skill reuses a working connection and verifies your workspace with whoami and list_operations. Both calls are free. Setup stops before paid research.

Connect Benchmark to Claude Code

Bring public content research into your AI workflow. Choose a client to connect.

Copy this prompt into your AI client for setup and free workspace verification.

Benchmark setup prompt

Use https://benchmark.social/skills/benchmark-setup/SKILL.md to connect Benchmark in this client. Reuse a working connection. Verify the workspace with whoami and list_operations. Stop after free setup verification. Ask for my task, scope, and credit budget before paid research.

Claude Use Benchmark in Claude, Cowork, or Claude Desktop. Set upHide

In Claude, go to Customize > Connectors, click +, choose Add custom connector, paste this URL, and click Add.

Open Claude connectors

Benchmark MCP URL

https://api.benchmark.app/mcp

ChatGPT Create a developer-mode MCP app on ChatGPT.com. Set upHide

Enable Developer Mode, then go to Settings > Apps and create a custom app with this URL. ChatGPT scans its tools and opens OAuth when required.

Open ChatGPT Apps setup

Benchmark MCP URL

https://api.benchmark.app/mcp

Claude Code Use Benchmark in Claude Code from your terminal or IDE. Set upHide

Run this in your terminal, then use /mcp in Claude Code to authenticate.

Claude Code command

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

Codex Use Benchmark in Codex or the ChatGPT desktop app. Set upHide

Codex CLI: add the Benchmark server in your terminal.

1. Add Benchmark

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

Then start the OAuth sign-in flow for Benchmark.

2. Sign in to Benchmark

codex mcp login benchmark

ChatGPT desktop app: open Settings > MCP servers, add a Streamable HTTP server, paste this URL, save, restart, then authenticate.

ChatGPT desktop MCP URL

https://api.benchmark.app/mcp

Grok Add Benchmark as a custom connector in Grok. Set upHide

Open grok.com/connectors, choose New connector → Custom, paste this URL, then sign in to Benchmark when Grok asks.

Open Grok connectors

Benchmark MCP URL

https://api.benchmark.app/mcp

Gemini CLI Use Benchmark in Gemini CLI from your terminal. Set upHide

Run this in your terminal, then run /mcp auth benchmark in Gemini CLI to sign in.

Gemini CLI command

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

Cursor Add Benchmark as a remote MCP server in Cursor. Set upHide

Paste this into Settings → Tools & MCP → New MCP Server, then connect Benchmark.

Cursor configuration

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

MCP endpoint

Use this URL in any MCP client that supports remote servers.

Benchmark MCP endpoint

https://api.benchmark.app/mcp

How clients sign in

Connecting a client opens the Benchmark sign-in page in your browser. After you sign in, the client uses the workspace selected in the workspace switcher. Clients that cannot open a browser can use an API key as the bearer token instead. Manage API keys.

Before you connect

1. Create a Benchmark account at benchmark.app.
2. Create a workspace, or accept an invite to one. If your account has no workspace, the server returns 403 FORBIDDEN.
3. Start a paid plan for the workspace. Paid operations need credits, and the dashboard MCP page shows the setup steps only when the workspace has an active paid plan. Hobby provides read-only MCP access; Pro and above can allow writes.

Authenticate

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

• Sign in with your Benchmark account (OAuth). Claude, ChatGPT, Claude Code, Codex, Grok, Gemini CLI, 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 ChatGPT to Benchmark

Connect ChatGPT to the production Benchmark MCP server at https://api.benchmark.app/mcp.

1. In ChatGPT on the web, enable developer mode if your account or workspace requires it.
2. Open Settings > Apps > Create. Workspace admins can instead use Workspace settings > Apps > Create.
3. Enter https://api.benchmark.app/mcp as the MCP server endpoint and choose OAuth when prompted.
4. Click Scan Tools, sign in to your Benchmark account, and wait for the scan to finish.
5. Click Create. Start a new chat, select the Benchmark app from the tools menu, and ask it to run whoami.

ChatGPT availability and who can create a custom MCP app depend on your plan, workspace settings, and role. See OpenAI’s developer mode and MCP apps guide for the current requirements.

Start research

After setup, give your client a task, scope, and credit budget. Then ask it to use the content research skill. Use it to break down one post or plan content for your business.

Request format: "markdown" for research results that you want to read or save locally. Keep the returned research and source links for later work. Avoid another paid read solely to change the format. Successful stored reads and completed refreshes spend workspace credits.

Tools

The server has up to four tools. mutate appears only when the plan, workspace setting, and server policy all allow writes. Hobby sessions list no mutation operations, including in list_operations.

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 operations available to this session. 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 REST JSON by default, or Markdown when you request it.
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 Pro or higher write-enabled 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":"@example_channel"}}}
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":"@example_channel"}}}}

Client → mutate {"operation":"refreshProfilesBasic","input":{"target":{"platform":"youtube","reference":"@example_channel"}}}
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 and mutate accept optional fields and format inputs. When the result has a data object, fields keeps only the top-level keys that you name. Collection results are not changed. Field selection occurs before formatting.

Set format to "json" or "markdown". The default is "json", which returns the REST JSON. Markdown uses headings, lists, and counts for posts and profiles. History pages use a table. Other result shapes use a JSON code block. Errors keep their JSON format. If fields removes the entity type, Markdown uses the JSON code block.

This synthetic example requests Markdown:

{
  "operation": "readPostsBasic",
  "input": {
    "target": { "platform": "youtube", "reference": "https://www.youtube.com/watch?v=example1234" }
  },
  "format": "markdown"
}

# Plan a lesson

youtube · video · 2026-10-14T12:00:00.000Z · example_teacher
https://www.youtube.com/watch?v=example1234
views 1,234 · likes 42

On Hobby, stored reads, polling and results stay available, but new refreshes return 403 PLAN_UPGRADE_REQUIRED with an upgradeUrl to the workspace billing page. A collection accepted before a plan change can still finish and be redeemed through REST or the CLI.

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 within the plan’s limit. Hobby allows at most Read-only. Read-only hides mutate; Off rejects every MCP connection for the workspace. The server’s operator setting may lower access further.
• 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. list_operations, whoami, and failed operations are free.

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, PLAN_UPGRADE_REQUIRED	Check access mode, membership or revocation; follow upgradeUrl for a plan refusal. 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, nextOperation, or upgradeUrl.

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, PLAN_UPGRADE_REQUIRED	Check membership, access mode or data permissions; follow upgradeUrl for a plan refusal.
404	NOT_FOUND, COLLECTION_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.