MCP Server

Canonical is a verified company graph for the long tail — the companies others miss. Unlike a web search that returns links to crawl and rank, describe what you want (or pass structured filters) and get a precise, LLM-verified, domain-keyed shortlist your agent can act on directly. Connect via the Model Context Protocol with Claude Desktop, Claude Code, ChatGPT, Cursor, or Windsurf.

Connect with One Click

No package install needed. No API key needed. Just add the remote server URL — OAuth handles authentication automatically.

{
  "mcpServers": {
    "canonical": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://trycanonical.ai/mcp/"]
    }
  }
}

claude mcp add canonical --transport http https://trycanonical.ai/mcp/

https://trycanonical.ai/mcp/

{
  "mcpServers": {
    "canonical": {
      "type": "streamable-http",
      "url": "https://trycanonical.ai/mcp/"
    }
  }
}

{
  "mcpServers": {
    "canonical": {
      "type": "streamable-http",
      "url": "https://trycanonical.ai/mcp/"
    }
  }
}

npx -y @smithery/cli install canonical-ai/company-search

Authentication & Permissions

Canonical uses OAuth 2.0 with Dynamic Client Registration — there are no manual API keys or client credentials to manage. Your MCP client (Claude, Cursor, ChatGPT, etc.) handles the OAuth handshake automatically on the first call.

See our Privacy Policy for how Canonical handles queries and tool calls made through the MCP server.

Limits & Pricing

MCP tool calls share the same credit balance and rate limits as the REST API. See pricing for plan tiers.

Tool Reference

The MCP server exposes five tools: search_companies, find_similar_companies, get_company_details, lookup_companies, and get_account_status. Domains (not internal numeric ids) are the public handle — pass a domain from any search result to get_company_details, find_similar_companies, or exclude_company_domains.

search_companies

Search the catalogue using structured parameters. Pass a free-text description for the semantic core (the only fuzzy field) plus typed filters for everything else. Constraints the engine can't enforce are reported in warnings — never silently dropped. Returns LLM-verified strong matches by default.

find_similar_companies

Given a seed company's domain, return canonically similar companies.

get_company_details

Drill into one company. Returns full canonical fields (name, description, hq, employees, funding, dimensions) plus a people list (founders + C-suite/execs) when leadership data is available. Response includes credits_used and credits_remaining. Costs 1 credit when the company is found (a not-found lookup is free), rate-limited.

Response also includes a leadership_data flag: "available" (people populated), "not_available" (company is in our DB but not in the leadership subset — most companies fall here), or "error" (transient lookup failure).

lookup_companies

Look up companies by name to disambiguate before passing a domain to other tools (e.g. as an exclusion or seed). Each input name returns ranked candidates plus a recommendation: when auto_resolve_recommended is true the match is unambiguous (use primary_candidate_domain); when false the name is a genuine toss-up — present the candidates and let the user pick. Costs 1 credit when at least one candidate is returned (a no-match lookup is free), rate-limited. Response includes credits_used and credits_remaining.

Per name: {confidence, auto_resolve_recommended, primary_candidate_domain, candidates: [{name, domain, headquarters, description, is_primary, payload_richness}]}. Follow auto_resolve_recommended — proceed silently when true, ask the user when false.

confidence: high = one candidate or all candidates are alias domains of one entity; medium = distinct entities but the top one dominates (≥5× the next entity's headcount and ≥100 employees, or the only candidate with a description); low = comparable distinct entities. Under auto_when_confident, high+medium auto-resolve and low asks. primary_candidate_domain is set and one candidate is is_primary: true only when auto-resolving; when asking, primary_candidate_domain is null and all candidates are is_primary: false (still ranked best-guess-first, but none authoritative).

get_account_status

Returns the org's credit balance, current plan, and search rate limits. Takes no parameters. Read-only, free — charges no credits. Use it to check remaining credits or pace requests before a large batch of searches.

Example Call & Response (search_companies)

Tool responses are structured JSON, not prose — the model can branch on fields directly:

# Example structured call
{
  "description": "AI diagnostic platforms for hospitals",
  "countries": ["United States"],
  "employee_size": "51-100",
  "founding_year_min": 2018,
  "funding_series": ["series_a", "series_b"],
  "top_k": 5,
  "intent": "sales_prospecting"
}

# Response
{
  "count": 2,
  "credits_used": 2,
  "credits_remaining": 980,
  "warnings": [],
  "results": [
    {
      "name": "Acme Health AI",
      "domain": "acmehealthai.com",
      "description": "AI-powered diagnostic platform...",
      "headquarters": "San Francisco, CA, United States",
      "employee_count": 75,
      "founding_year": 2019,
      "funding": { "latest_series": "series_b", "latest_amount_usd": 45000000 },
      "dimensions": { "industry": ["Healthcare"], "offering_type": ["Software"] },
      "verdict": "relevant",
      "verdict_reason": "1. Products...: AI diagnostic platform matches..."
    }
  ]
}

Note: the domain field is the public handle for a company — pass it to get_company_details, find_similar_companies, or exclude_company_domains. Internal numeric ids aren't exposed.

Troubleshooting