Setup CitationBench in a custom MCP client or agent host
Connect any compliant MCP client to the hosted CitationBench server over streamable HTTP. Standard tools/list and tools/call, bearer auth, per-call workspace scoping for custom agents.
For developers building their own MCP host (a custom agent, an internal tool, a bot). The CitationBench MCP server speaks standard MCP over HTTP — any compliant client can connect.
Connection details
| Endpoint | https://mcp.citationbench.com/mcp |
| Transport | HTTP (streamable) |
| Auth | Authorization: Bearer sk_live_*** (or omit for demo mode) |
| Workspace | X-Workspace-Id: ws_*** (per connection; or per tool call via workspace arg) |
| Protocol | Model Context Protocol 0.x |
Tool discovery
Standard MCP tools/list:
{
"method": "tools/list",
"params": {}
}Returns ~130 tools across the agent.*, research.*, produce.*, indexing.*, link_building.* namespaces.
For just a subset (e.g., research tools only), the server also supports tools/list with a namespace filter:
{
"method": "tools/list",
"params": { "namespace": "research" }
}Calling a tool
Standard MCP tools/call:
{
"method": "tools/call",
"params": {
"name": "research.keyword.research",
"arguments": {
"seed": "project management software",
"depth": "fast",
"limit": 50
}
}
}Long-running tools
Most CitationBench tools are async (return an invocation handle). The MCP server sends progress as MCP notifications while the invocation runs, then returns the final result.
Notification types:
tool/progress— pct + step nametool/log— agent narrationtool/awaiting_approval— invocation paused for approval
Your client should:
- Receive notifications between request and final response
- Render them inline so the user sees progress
- Handle
tool/awaiting_approvalby surfacing the preview to the user and routing approve/reject back via theagent.approval.*tools
Session model
Stateless per request. Each request includes auth. There's no MCP server-side session token to manage.
Code samples
TypeScript (@modelcontextprotocol/sdk)
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { HttpClientTransport } from "@modelcontextprotocol/sdk/client/http.js";
const transport = new HttpClientTransport({
url: "https://mcp.citationbench.com/mcp",
headers: {
Authorization: `Bearer ${process.env.CITATIONBENCH_API_KEY}`,
"X-Workspace-Id": process.env.WORKSPACE_ID!,
},
});
const client = new Client(
{ name: "my-agent", version: "0.1.0" },
{ capabilities: {} },
);
await client.connect(transport);
// Discover tools
const { tools } = await client.listTools();
// Call a tool
const result = await client.callTool({
name: "research.keyword.research",
arguments: { seed: "project management software", depth: "fast" },
});Python (mcp)
from mcp.client.session import ClientSession
from mcp.client.http import http_client
import os
async with http_client(
url="https://mcp.citationbench.com/mcp",
headers={
"Authorization": f"Bearer {os.environ['CITATIONBENCH_API_KEY']}",
"X-Workspace-Id": os.environ['WORKSPACE_ID'],
},
) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
result = await session.call_tool(
"research.keyword.research",
{ "seed": "project management software", "depth": "fast" },
)Raw HTTP
curl -X POST https://mcp.citationbench.com/mcp \
-H "Authorization: Bearer $CITATIONBENCH_API_KEY" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "research.keyword.research",
"arguments": { "seed": "project management software", "depth": "fast" }
}
}'Errors
All standard JSON-RPC errors. CitationBench-specific:
| Code | Meaning |
|---|---|
-32001 | unauthorized — token missing / invalid (and endpoint doesn't allow demo) |
-32002 | workspace_forbidden |
-32003 | insufficient_credits |
-32004 | rate_limited |
-32005 | unknown_tool |
Tool surface stability
The MCP tool surface follows the same versioning as the REST API. /v1/ is stable; breaking changes follow a 12-month deprecation window. Beta tools live under the *.beta.* namespace.
What to try next
- Catalog — every tool
- Errors — full error code list (REST + MCP share codes)
- Authentication
- Concept · Agent
ChatGPT Apps
Add the hosted CitationBench MCP server to ChatGPT as a custom App. Three-minute install lets ChatGPT Plus, Pro, Enterprise, or Edu users call ~130 SEO and GEO tools.
Keyword research in 20 min
Hand a domain to the bootstrap_brand agent and get back ICP, 800–1,500 labeled keywords, competitor map, Reddit pain points, a 12-week content plan, and 6 landing-page briefs.