canonical-search 0.1.1

Python SDK for Canonical company search — find companies using natural language

canonical-search

Python SDK and MCP server for Canonical company search. Find companies using natural language.

Install

SDK only (for use in your Python code)

pip install canonical-search

MCP server (for Claude Desktop, Cursor, Windsurf, Claude Code)

We recommend pipx which installs in an isolated environment and avoids conflicts with system Python:

pipx install "canonical-search[mcp]"

Alternatively, with pip:

pip install "canonical-search[mcp]"

Quick Start

from canonical_search import CanonicalClient

client = CanonicalClient(api_key="sk_your_key")

# Sync
results = client.search("AI healthcare startups")
for company in results.results:
    print(f"{company.name} — {company.domain}")

# Async
results = await client.asearch("B2B fashion tech companies")

Parameters

Parameter	Type	Default	Description
query	str	required	Natural language search query
top_k	int	20	Number of results (1-100)
verified	bool	False	LLM verification for higher accuracy (uses 2 credits)

Environment-Based Config

Instead of passing api_key directly, you can use environment variables:

export CANONICAL_API_KEY=sk_your_key
export CANONICAL_API_BASE_URL=https://trycanonical.ai  # optional
export CANONICAL_TIMEOUT=30.0  # optional

from canonical_search.config import client_from_env

client = client_from_env()
results = client.search("fintech companies in Europe")

MCP Server

For AI tools that support MCP (Claude Desktop/Cowork, Cursor, Windsurf, Claude Code).

First, find the absolute path to the binary:

which canonical-mcp

Claude Desktop / Cowork

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "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"
      }
    }
  }
}

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

Framework Integration

The SDK works with any Python-based AI agent framework with minimal glue code.

AutoGen

from autogen import register_function
from canonical_search import CanonicalClient

client = CanonicalClient(api_key="sk_your_key")

def search_companies(query: str, top_k: int = 20) -> str:
    """Search for companies using natural language."""
    return client.search(query, top_k).model_dump_json()

register_function(
    search_companies,
    caller=assistant,
    executor=executor,
    description="Search for companies using natural language",
)

LangChain

from langchain_core.tools import tool
from canonical_search import CanonicalClient

client = CanonicalClient(api_key="sk_your_key")

@tool
def search_companies(query: str, top_k: int = 20) -> str:
    """Search for companies using natural language."""
    return client.search(query, top_k).model_dump_json()

Agno

from agno.tools import tool
from canonical_search import CanonicalClient

client = CanonicalClient(api_key="sk_your_key")

@tool
def search_companies(query: str, top_k: int = 20) -> str:
    """Search for companies using natural language."""
    return client.search(query, top_k).model_dump_json()

CrewAI

from crewai.tools import tool
from canonical_search import CanonicalClient

client = CanonicalClient(api_key="sk_your_key")

@tool("Company Search")
def search_companies(query: str, top_k: int = 20) -> str:
    """Search for companies using natural language."""
    return client.search(query, top_k).model_dump_json()

Response Schema

SearchResponse:
    results: list[Company]  # List of matching companies
    count: int              # Number of results
    query: str              # Original query
    credits_used: int       # Credits consumed
    credits_remaining: int  # Remaining credits (if available)

Company:
    id: int
    name: str
    website: str
    logo_url: str | None
    domain: str
    description: str
    verdict: str | None         # Only when verified=True
    verdict_reason: str | None  # Only when verified=True

Get an API Key

1. Sign up at trycanonical.ai
2. Go to Dashboard → API Keys
3. Create a new key (starts with sk_)