# Canonical — Company Discovery for Agents

> Find the companies others miss. **[Canonical](https://trycanonical.ai)** is a verified,
> LLM-checked company graph — not a web search. Describe what you want in plain English (or
> pass structured filters) and get a precise, **domain-keyed shortlist of the long-tail,
> net-new accounts** that keyword/firmographic databases (Apollo, ZoomInfo) systematically miss.

This is the public home of Canonical's remote **MCP server** and its **Claude Code plugin +
discovery skill**. The server is hosted — there's nothing to run locally.

## What you can do

- **Build a target-account list from a plain-English ICP** — including the long-tail companies Apollo/ZoomInfo don't have.
- **Expand from a seed company → a lookalike / TAM list** (multi-axis similarity, not keyword overlap).
- **Turn a messy company name into a verified domain + full profile** (founders/execs, funding, HQ, dimensions).
- **Drop Canonical into an existing GTM / recruiting / investor-research agent** as the discovery layer that feeds your enrichment and outreach tools.

Canonical **discovers and verifies companies**. It is not an outreach sender and not a contact
database — it finds the accounts, then hands off to whatever enrichment/outreach tooling you
already use (Apollo, Clay, your CRM, a sales agent).

## Get started (Claude Code)

Install the plugin — it wires up the MCP server **and** the discovery skill in one step:

```
/plugin marketplace add vy-labs/canonical-mcp
/plugin install canonical@canonical-mcp
```

Then either run the slash command with an ICP or a seed domain:

```
/canonical:find-accounts B2B SaaS building AI agents for sales teams, US, seed to Series A
/canonical:find-accounts stripe.com
```

…or just describe what you're looking for in plain language — the `find-net-new-accounts` skill triggers automatically:

> "Find companies like stripe.com but headquartered in Europe."

On the first tool call, your browser opens Canonical's OAuth consent page (no API key to copy;
250 free credits on signup, no card).

## Install (other clients)

The MCP server works in any MCP client. Point it at the streamable-HTTP endpoint and authorize
via OAuth — full per-client setup at https://trycanonical.ai/documentation/mcp.

- **Server URL:** `https://trycanonical.ai/mcp`
- **Transport:** Streamable HTTP · **Auth:** OAuth 2.0 with dynamic client registration (scope `search`), read-only

> **Using ChatGPT?** No config needed — Canonical is a published ChatGPT app: **[Canonical Company Search](https://chatgpt.com/plugins/plugin_asdk_app_6a1ed22d523481918b6f6d8ab74b8052)** → click **Try in chat**. Authorizes via OAuth on first use (250 free credits).

<details>
<summary><b>Cursor</b></summary>

Install from the Cursor marketplace, or add to `~/.cursor/mcp.json` (global) or `<project>/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "canonical": { "url": "https://trycanonical.ai/mcp", "type": "streamable-http" }
  }
}
```
</details>

<details>
<summary><b>Claude Desktop / claude.ai</b></summary>

Add a custom connector with the URL `https://trycanonical.ai/mcp` and complete the OAuth flow.
Step-by-step: https://trycanonical.ai/documentation/mcp
</details>

<details>
<summary><b>VS Code (Copilot)</b></summary>

```json
{
  "servers": {
    "canonical": { "type": "http", "url": "https://trycanonical.ai/mcp" }
  }
}
```
</details>

<details>
<summary><b>Codex CLI</b></summary>

```
codex mcp add canonical --url https://trycanonical.ai/mcp
```

Or in `~/.codex/config.toml`:

```toml
[mcp_servers.canonical]
url = "https://trycanonical.ai/mcp"
```

No token needed — Codex runs the OAuth flow automatically on first use. Verify with `/mcp`.
</details>

<details>
<summary><b>opencode</b></summary>

In `opencode.json`:

```json
{
  "mcp": {
    "canonical": { "type": "remote", "url": "https://trycanonical.ai/mcp", "enabled": true }
  }
}
```

opencode prompts you to authorize on first use.
</details>

<details>
<summary><b>stdio-only clients (no native remote-MCP support)</b></summary>

Bridge the remote server through [`mcp-remote`](https://github.com/geelen/mcp-remote) as the server command:

```
npx mcp-remote https://trycanonical.ai/mcp
```

It converts stdio ↔ streamable-HTTP and carries the OAuth flow.
</details>

<details>
<summary><b>Any MCP client</b></summary>

Point it at the streamable-HTTP endpoint `https://trycanonical.ai/mcp` and authorize via OAuth.
Full client-by-client setup: https://trycanonical.ai/documentation/mcp
</details>

## The discovery skill

`plugins/canonical/skills/find-net-new-accounts/` — a portable [Agent Skill](https://code.claude.com/docs/en/skills)
that runs the discovery motion: **ICP or seed → verified long-tail accounts → decision-maker +
LinkedIn → hand off to your enrichment/outreach tools.** It uses Canonical for the discovery leg
even when Apollo/ZoomInfo/Clay are co-connected (Canonical is strong on long-tail company
coverage, those tools on contacts — each does what it's best at), and it never guesses or scrapes
emails: when no enrichment tool is present it hands off the verified account + LinkedIn instead.

The `SKILL.md` is standard Agent-Skills format and is also mirrored at the repo root
(`skills/find-net-new-accounts/`), so you can install it into Codex, Cursor, opencode, Cline, and
other [agentskills.io](https://agentskills.io)-compatible agents in one line:

```
npx skills add vy-labs/canonical-mcp
```

Pair it with the MCP server (above) in that same client, and you get the guided motion outside
Claude Code too — install → authorize → start.

---

## Reference

### Tools

The server exposes five read-only tools:

| Tool | Purpose | Credits |
|------|---------|---------|
| `search_companies` | Structured search — free-text `description` + typed filters (location, employee size, funding stage/amount/investor, founder attributes, exclusions). Unsupported constraints are reported back, never silently dropped. | spends |
| `find_similar_companies` | Look-alikes of a seed domain; multi-axis rerank (semantics, dimensions, funding, geo, investors, size). | spends |
| `get_company_details` | Full profile for one domain incl. founders/execs + prior-employer category tags (FAANG/unicorn/MBB). | 1 when it resolves |
| `lookup_companies` | Disambiguate a free-text name → canonical domain; ranked candidates with confidence. | 1 per call with ≥1 candidate |
| `get_account_status` | Credit balance, plan, rate limits. | free |

### Auth & pricing

- **Auth:** OAuth 2.0 with dynamic client registration (scope `search`). Read-only — no destructive operations. On first use your client opens the OAuth consent flow in the browser; there's no API key to copy.
- **Free tier:** 250 credits on signup, no credit card required.
- **Docs:** https://trycanonical.ai/documentation/mcp
- **Privacy:** https://trycanonical.ai/privacy-policy · **Terms:** https://trycanonical.ai/terms · **Support:** support@trycanonical.ai

### Listed on

[Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=ai.trycanonical/company-search) (`ai.trycanonical/company-search`) · [Smithery](https://smithery.ai/servers/canonical-ai/company-search)

### Example prompts

- "Find fintech startups in India that raised Series A in the last 6 months."
- "Show me companies similar to stripe.com but headquartered in Europe."
- "Who are the founders of anthropic.com and where did they work before?"
- "List YC-backed B2B SaaS companies with a technical cofounder."

### Repository contents

| Path | What |
|------|------|
| `.claude-plugin/marketplace.json` | Claude Code marketplace manifest (makes this repo installable via `/plugin marketplace add`). |
| `plugins/canonical/` | The Claude Code plugin: `.mcp.json` (remote server) + `.claude-plugin/plugin.json` + the command and skill. |
| `plugins/canonical/commands/find-accounts.md` | The `/canonical:find-accounts` slash command. |
| `plugins/canonical/skills/find-net-new-accounts/` | The `find-net-new-accounts` Agent Skill bundled in the plugin (Claude Code). |
| `skills/find-net-new-accounts/` | Same skill mirrored at repo root for cross-client `npx skills add`. |
| `.cursor-plugin/plugin.json` | Cursor plugin manifest. |
| `mcp.json` | Remote server config — used by the Cursor plugin and copy-pasteable into any client. |

## License

MIT — see [LICENSE](./LICENSE). This license covers the contents of this repository
(manifests + docs + skill); the Canonical service itself is operated at https://trycanonical.ai
under its own [terms](https://trycanonical.ai/terms).