Connect LLM agents to CipherCue

What is MCP?

MCP (Model Context Protocol) is Anthropic's open standard for letting LLM agents discover and call external tools over a uniform interface. With CipherCue's MCP server connected, you can ask Claude or Cursor questions like "find German companies running Fortinet VPNs" or "give me the dossier for ciphercue.com" and the agent will call the right tool and synthesise an answer over the structured response.

CipherCue's MCP server is hosted at https://ciphercue.com/mcp. It speaks the Streamable HTTP transport, so no local install or npm package is needed: paste the URL plus your CipherCue API token into your agent's MCP configuration.

Generate an API token

MCP reuses the same workspace API tokens as the REST API. Owners and admins can issue tokens from Settings › API tokens.

1. Open Settings › API tokens.
2. Choose Create token. Give it a descriptive name (e.g. claude-desktop-chris).
3. Tick the abilities your tools need (most workflows want all four):
   • read:entities — required for search_entities, get_entity, match_domains, tech_vendor_search
   • read:facts — required for get_entity_facts, get_entity_changes, tech_vendor_search
   • read:signals — required for list_signals
   • read:accounts — required for list_accounts
4. Copy the token shown on the next screen. The full token is only visible once. Store it in your password manager.

Claude Desktop setup

Open the Claude Desktop config file. The path depends on your operating system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add (or extend) the mcpServers object:

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

Fully quit Claude Desktop (Cmd+Q on macOS — not just close the window) and reopen it. On first launch, npx will download mcp-remote from npm (10–20 seconds). Open a new conversation and click the tool picker; you should see eight CipherCue tools listed.

Why not the "Add custom connector" GUI?

Claude Desktop's in-app Add custom connector dialog only accepts MCP servers that implement the full OAuth 2.1 authorisation flow with dynamic client registration. CipherCue uses workspace API tokens (bearer auth), which is simpler to issue and revoke per integration but not what the GUI dialog expects. The mcp-remote shim is the official path for bearer-auth servers and works identically once connected.

Cursor setup

Open Cursor's settings, navigate to Features › MCP, and add a new MCP server:

{
  "name": "ciphercue",
  "url": "https://ciphercue.com/mcp",
  "headers": {
    "Authorization": "Bearer cc_pat_your_token_here"
  }
}

Cursor will probe the connection and list the available tools when the server is reachable.

Claude Code setup

From a terminal, register the MCP server with the claude CLI:

claude mcp add ciphercue \
  --transport http \
  --url https://ciphercue.com/mcp \
  --header "Authorization: Bearer cc_pat_your_token_here"

List configured servers to confirm:

claude mcp list

End-to-end walkthrough

This 90-second screen recording walks through token generation, Claude Desktop config, and a sample query.

Available tools

Eight tools are exposed. Use natural-language prompts and the agent will pick the right one.

Sample prompts

• "Search CipherCue for German companies running Fortinet VPNs."
• "Give me the full dossier for ciphercue.com."
• "What changed for entity {uuid} in the last 14 days?"
• "Match this list of domains to CipherCue entities: acme.com, contoso.eu, example.fr."
• "List all critical signals from the past week."

Quota and rate limits

MCP calls count against the same monthly API quota as the REST API:

• Free: API tokens unavailable.
• Paid: 1,000 calls / month.
• Enterprise: 100,000 calls / month.

Each MCP tool call counts as one API call, with one exception: match_domains charges one call per domain in the batch (a 50-domain batch consumes 50 calls). Burst limit is 60 requests per minute per token.

Every response includes X-Quota-Limit, X-Quota-Remaining, and X-Quota-Reset headers so you can see your current usage.

Troubleshooting

403 tier_required

Your workspace is on the Free tier. MCP requires Paid or Enterprise. Upgrade in settings.

401 Unauthenticated

The bearer token is missing, malformed, or revoked. Generate a fresh token from Settings › API tokens.

Tools don't appear in the picker

The token is missing the abilities the tool requires. The MCP server still connects (so the agent shows it as available), but individual tool calls fail. Regenerate the token with all four abilities ticked.

429 monthly_quota_exceeded

You've hit the monthly call cap. Quota resets at the start of next month UTC. Enterprise quota uplifts are available — contact us.

Tool call returns "opt_out"

That specific entity has opted out of public observation via DNS TXT or email to abuse@ciphercue.com. The entity is filtered from MCP responses to honour the opt-out.

Claude Desktop's "Add custom connector" dialog rejects the URL

The in-app dialog requires OAuth 2.1 with dynamic client registration; CipherCue uses bearer tokens. Use the mcp-remote shim in the config file instead.

Claude Desktop shows "Some MCP servers could not be loaded"

You likely added a url + headers block to claude_desktop_config.json. That format is not supported there — Claude Desktop's config file only accepts stdio servers (command + args). Switch to the mcp-remote config shown above.