MCP Server

Give AI assistants access to Canonical's company search via the Model Context Protocol. Works with Claude Desktop, Claude Code, Cursor, and Windsurf.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants use external tools. When you install the Canonical MCP server, your AI assistant can search for companies directly during a conversation — no manual API calls needed.

Installation

We recommend pipx for an isolated install that won't conflict with other Python packages:

pipx install "canonical-search[mcp]"

Or with pip: pip install "canonical-search[mcp]"

Verify the installation:

which canonical-mcp
# /Users/you/.local/bin/canonical-mcp

Save this path — you'll need it for the configuration below.

IDE Setup

Claude Desktop

Edit your config file:

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

{
  "mcpServers": {
    "canonical": {
      "command": "/full/path/to/canonical-mcp",
      "env": {
        "CANONICAL_API_KEY": "sk_your_key"
      }
    }
  }
}

Then fully quit and restart Claude Desktop.

Claude Code

claude mcp add canonical -- canonical-mcp

# Set your API key in the environment:
export CANONICAL_API_KEY=sk_your_key

Cursor

Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "canonical": {
      "command": "/full/path/to/canonical-mcp",
      "env": {
        "CANONICAL_API_KEY": "sk_your_key"
      }
    }
  }
}

Windsurf

Same JSON format as Cursor — add to your Windsurf MCP config:

{
  "mcpServers": {
    "canonical": {
      "command": "/full/path/to/canonical-mcp",
      "env": {
        "CANONICAL_API_KEY": "sk_your_key"
      }
    }
  }
}

Common issue: Always use the full absolute path from which canonical-mcp. Relative paths are the most common cause of MCP connection failures.

Tool Reference

The MCP server exposes a single tool: search_companies

Parameter	Type	Default	Description
query	string	required	Natural language query (e.g. "B2B fashion tech companies")
top_k	integer	20	Number of results (1–100)
verified	boolean	false	LLM verification (slower, uses 2 credits)

Example Output

When an AI assistant calls this tool, it receives formatted markdown:

Found 20 companies for 'AI healthcare startups' (1 credits used)

**Acme Health AI** — acmehealthai.com
  AI-powered diagnostic platform for healthcare providers...

**MedTech Solutions** — medtechsolutions.com
  Clinical decision support system using machine learning...

Credits remaining: 998