MCP Server | ClearSERP

ClearSERP runs a remote Model Context Protocol server at https://clearserp.com/mcp (Streamable HTTP). Any MCP client can call the same operations as the REST API: an agent can estimate cost, start research, wait for it, read every tab of an Auto Research report and save keywords to a collection. Authentication is an API key from the settings page, sent as a bearer token; the key's scopes and spend limits apply to everything the agent does.

Tip

Give agents their own key with a daily or monthly credit cap and, if you like, no Auto Research (or a maximum tier). The server also tells the model to confirm with you before approving an Auto Research plan unless you asked it to run one.

Any MCP client

The server is vendor-neutral: it speaks standard MCP over Streamable HTTP and needs only two settings, the URL https://clearserp.com/mcp and an Authorization: Bearer <key> header. Wherever your client asks for a remote (HTTP) MCP server, enter those. The sections below show the exact form for common clients.

Cursor, Devin Desktop and other JSON-configured clients

Add to .cursor/mcp.json (Cursor), ~/.codeium/windsurf/mcp_config.json (Devin Desktop, formerly Windsurf; existing Windsurf MCP settings carry over), or the equivalent file. The settings page's "Copy MCP config" button produces this block with your key filled in.

{
  "mcpServers": {
    "clearserp": {
      "url": "https://clearserp.com/mcp",
      "headers": { "Authorization": "Bearer csk_your_key_here" }
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml. Keep the key out of the file if you prefer by using an environment variable.

[mcp_servers.clearserp]
url = "https://clearserp.com/mcp"
http_headers = { Authorization = "Bearer csk_your_key_here" }

# or, reading the key from the CLEARSERP_API_KEY environment variable:
# bearer_token_env_var = "CLEARSERP_API_KEY"

Claude Code

claude mcp add --transport http clearserp https://clearserp.com/mcp \
  --header "Authorization: Bearer csk_your_key_here"

VS Code (GitHub Copilot agent mode)

Add to .vscode/mcp.json in the workspace, or to your user settings under mcp.servers.

{
  "servers": {
    "clearserp": {
      "type": "http",
      "url": "https://clearserp.com/mcp",
      "headers": { "Authorization": "Bearer csk_your_key_here" }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json.

{
  "mcpServers": {
    "clearserp": {
      "httpUrl": "https://clearserp.com/mcp",
      "headers": { "Authorization": "Bearer csk_your_key_here" }
    }
  }
}

Clients without remote-server support

Some desktop apps only launch local (stdio) servers. Use the mcp-remote bridge, which speaks stdio to the client and HTTP to ClearSERP:

{
  "mcpServers": {
    "clearserp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://clearserp.com/mcp", "--header", "Authorization: Bearer csk_your_key_here"]
    }
  }
}

From your own agent code

LLM APIs that accept remote MCP servers take the same two values. With the Claude API's MCP connector, for example:

"mcp_servers": [{
  "type": "url",
  "url": "https://clearserp.com/mcp",
  "name": "clearserp",
  "authorization_token": "csk_your_key_here"
}]

With the OpenAI Responses API, pass a tool of type mcp with server_url and the bearer header in headers. Any MCP client SDK (TypeScript, Python) can also connect directly with its Streamable HTTP transport and the same header.

Tools

Tools	Purpose
get_account, estimate_cost, get_usage	Credits, limits and what a job will cost
list_locations, list_languages	Reference data
start_analysis, get_analysis, get_analysis_results, list_analyses	Keyword analysis
start_research, get_research, get_research_results, list_research, analyze_research_keywords	The five research modes
create_auto_research_plan, get_auto_research_plan, list_auto_research_plans, update_auto_research_plan, revise_auto_research_plan, approve_auto_research_plan	Auto Research plans
get_auto_research_run, list_auto_research_runs, get_auto_research_report, get_auto_research_articles, get_auto_research_topics, get_auto_research_map, get_auto_research_keywords, regroup_auto_research, rewrite_auto_research_titles	Auto Research runs and every tab of the report
list_collections, create_collection, get_collection_keywords, save_keywords_to_collection, delete_collection	Collections
list_events, list_webhooks, create_webhook, delete_webhook	Events and webhooks

Jobs are asynchronous. The get_* tools accept a wait argument (seconds) that long-polls until the job finishes, so an agent can say "start the research, then wait for it" without spinning. Long Auto Research runs take many calls; a webhook is the better signal for unattended workflows.

A typical session

User: Find the best article opportunities for my soap store, soapworks.example.
Agent: get_account → 3,200 credits available; key allows Auto Research up to Thorough.
Agent: "Which tier: Quick (500 credits), Thorough (2,000) or Exhaustive (4,000)?"
User: quick
Agent: create_auto_research_plan { brief: "…", domain: "soapworks.example", tier: "quick" }
Agent: get_auto_research_plan { id, wait: 25 } → draft with 8 seeds, 3 competitors, estimatedCredits 500
Agent: "The plan targets X, Y and Z. It will cost 500 credits. Approve?"
User: yes
Agent: approve_auto_research_plan { id, expectedCredits: 500 } → run started
Agent: get_auto_research_run { id, wait: 25 } … (repeats until completed)
Agent: get_auto_research_report → get_auto_research_articles { limit: 25 }
Agent: summarises the top articles and the topical map

Protocol notes

Streamable HTTP, stateless: every request is a single POST that returns JSON. No session ids, no server-sent events.
Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05 are accepted.
Tool results include both a text block and structuredContent with the same JSON.
Errors from the platform (no credits, spend limit, not found) come back as tool results with isError: true and the REST error body, so the model can explain them.
An invalid key returns HTTP 401 with a JSON-RPC error. There is no OAuth flow; configure the bearer header.