> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Topo MCP connector

> Connect Claude and other MCP clients to your Topo workspace: tools, scopes, sign-in, safeguards, lead data sources, and troubleshooting.

The Topo MCP connector lets an AI assistant such as Claude work in your Topo
workspace: triage replies, clear tasks, review waiting leads, run sequences,
source new leads, and manage your exclusion list. It is the same workspace you
use in the Topo app, reached through the
[Model Context Protocol](https://modelcontextprotocol.io).

* **Server URL:** `https://mcp.topo.io/mcp` (streamable HTTP)
* **Requirement:** a Topo account. The connector only sees the workspace your
  Topo user belongs to.

## Connect and sign in

<Steps>
  <Step title="Add the connector">
    In Claude, open **Customize → Connectors**, click **Add custom connector**,
    and paste `https://mcp.topo.io/mcp`. The same URL works in any MCP client
    that supports OAuth.
  </Step>

  <Step title="Sign in and consent">
    The first tool call opens a Topo sign-in (OAuth 2.0 with PKCE). The consent
    screen names the application asking for access and the permissions below.
    Nothing is shared until you accept.
  </Step>

  <Step title="Revoke access">
    Remove the connector from your MCP client to revoke it. A consent is
    remembered for 90 days at most, after which you are asked again.
  </Step>
</Steps>

Clients that cannot run OAuth can authenticate with a Topo API key created in
**Settings → Developers**, sent as a bearer token. The key's scopes limit what
the tools can do.

## Permissions

| OAuth scope | What it grants |
| - | - |
| `mcp:read` | Read contacts, accounts, lists, sequences, tasks, inbox threads, activities, exclusions, signals, playbooks and their runs, events, webhooks, CRM deals, and workspace members. |
| `mcp:write` | Everything in `mcp:read`, plus writes on the same records: replies, task outcomes, enrollments, lists, exclusions, sequence templates, signals, playbooks, CRM fields, webhooks, and lead search runs. |

Every tool declares the scope it needs, and a tool the credential does not
cover returns an error instead of running.

## Tools

The connector publishes about 170 tools. Every tool carries MCP annotations:
`readOnlyHint` on reads, `destructiveHint` on anything that sends a message,
starts or stops outreach, spends credits, overwrites a value without keeping
the previous one, or cannot be undone in one step, and `openWorldHint` when
it reaches a third party (an email recipient, an enrichment, lead-data
or signal provider, a web search, a webhook endpoint), directly or
through the outreach or automation it turns on.

| Area | Main tools |
| - | - |
| Inbox and replies | `list_threads`, `get_thread`, `reply_to_message`, `categorize_reply`, `archive_thread` |
| Tasks | `list_tasks`, `get_task`, `resolve_task`, `snooze_task`, `create_todo` |
| Sequences | `list_sequence_templates`, `get_sequence_template`, `create_sequence_template`, `clone_sequence_template`, `update_sequence_template_steps`, `update_sequence_template_settings`, `set_sequence_template_senders`, `set_sequence_template_status`, `get_sequence_metrics` |
| Enrollments | `enroll`, `approve_leads`, `refuse_leads`, `pause_sequence`, `resume_sequence`, `stop_sequence`, `unenroll`, `update_sequence_steps` |
| Contacts and accounts | `list_contacts`, `get_contact`, `create_or_update_contact`, `list_accounts`, `get_account`, `find_or_create_account`, `enrich_contact`, `get_and_enrich_contact`, `enrich_account`, `qualify_lead`, `update_crm_field` |
| Lists and imports | `create_contact_list`, `add_contact_list_members`, `import_leads`, `import_csv`, `create_account_list` |
| Lead search | `create_lead_search`, `refine_lead_search`, `preview_lead_search`, `run_lead_search`, `get_lead_search`, `list_lead_search_results`, `import_lead_search_results` |
| Exclusions | `list_exclusions`, `add_contact_exclusions`, `add_domain_exclusions`, `update_exclusion`, `remove_exclusion` |
| Signals | `list_signal_presets`, `preview_signal`, `create_signal`, `update_signal_config`, `pause_signal`, `archive_signal` |
| AI variables | `list_ai_variables`, `draft_ai_variable`, `simulate_ai_variable`, `create_ai_variable`, `update_ai_variable`, `estimate_ai_variable_run`, `run_ai_variable`, `get_ai_variable_values`, `delete_ai_variable` |
| Playbooks | `list_playbooks`, `get_playbook`, `list_playbook_templates`, `get_playbook_building_blocks`, `list_playbook_field_options`, `create_playbook`, `get_playbook_draft`, `edit_playbook_draft`, `discard_playbook_draft`, `test_playbook_step`, `start_playbook_test_run`, `stop_playbook_test_run`, `list_playbook_test_cases`, `create_playbook_test_case`, `publish_playbook`, `list_playbook_versions`, `rollback_playbook`, `set_playbook_status`, `run_playbook`, `list_playbook_runs`, `get_playbook_run`, `list_playbook_parameters`, `set_playbook_parameter`, `delete_playbook` |
| Knowledge, webhooks | `search_knowledge_documents`, `get_knowledge_document`, `create_webhook`, `ingest_event` |
| Discovery | `whoami`, `search`, `fetch` |

The complete, machine-readable list with every input schema is served by the
server itself (`tools/list`).

## Safeguards

Some decisions stay with a person in the Topo app, whatever the assistant is
asked to do:

* **Opt-outs cannot be undone from the connector.** An exclusion whose reason
  is `UNSUBSCRIBED` or `CONTACT_REFUSED` cannot be removed, have its expiry
  date changed, or be relabeled over MCP. Lifting one is done by a person in
  **Settings → Organization → Exclusions**.
* **Unsubscribe rules cannot be overridden per sequence.** The per-sequence
  reply-exclusion override never changes how unsubscribe replies are handled.
* **Account exclusions cannot be bypassed.** Letting a sequence contact
  companies on the account exclusion list is only possible in the app.
* **Nobody is contacted without approval.** Sequences created or cloned over
  MCP hold every new lead until someone approves it (`COPILOT`), and the
  connector cannot switch a sequence to automatic approval (`AUTOPILOT`).
  `approve_leads` takes the explicit list of leads a person chose.
* **Enrollment keeps its protections.** `enroll` skips anyone already in a
  running sequence, and re-enrolls people with past sequences only after a
  cooldown of at least 90 days. Exclusions are checked before enrollment and
  again before every step.
* **Spending credits is confirmed.** Running a lead search requires an explicit
  confirmation of the volume (see below). Running an AI variable on the rows of
  the Accounts or Contacts table, or of one list or sequence, requires
  `confirmed_by_user=true` after you
  have seen the `estimate_ai_variable_run` quote; a failed value is never
  charged.
* **Playbooks are tested before they go live.** `publish_playbook` refuses a
  definition without a passing test run unless you explicitly ask to publish
  it untested. Publishing, turning a playbook on, rolling back and deleting
  ask for your confirmation. Authoring requires a signed-in user: an API key
  can read playbooks but not change them.
* **Playbooks only run connector tools.** Over MCP, a playbook can only be run
  or tested when every step uses an action that is also a tool of the
  connector. A playbook that calls an HTTP endpoint, notifies a teammate, or
  runs a free-form AI step runs from the Topo app.
* **Secrets never pass through the connector.** `set_playbook_parameter`
  stores plain values only. Secrets and credentials are entered by a person
  on the playbooks **Vault** page, which the tool links to.

## Lead search flow

Lead search finds new prospects in Topo's lead database and never spends
credits before the user confirms the volume.

<Steps>
  <Step title="Draft">
    `create_lead_search` turns a description ("VPs of Sales at French SaaS
    companies over 50 employees") into filters and returns a summary for the
    user to review. Nothing is fetched yet.
  </Step>

  <Step title="Refine">
    `refine_lead_search` applies one change at a time ("remove France", "only
    over 100 employees") and returns the updated summary.
  </Step>

  <Step title="Preview (optional)">
    `preview_lead_search` samples up to 25 matching leads cheaply, to check the
    filters before a full run.
  </Step>

  <Step title="Run">
    `run_lead_search` sources up to the requested number of leads and spends
    credits. It only starts when called with `confirmed_by_user=true`, which
    the assistant sets once the user agreed to that volume. It returns at once;
    `get_lead_search` reports progress.
  </Step>

  <Step title="Review and import">
    `list_lead_search_results` pages through what was found, and
    `import_lead_search_results` adds the chosen leads, or a number of them the
    user picked, to a contact list. The volume is capped by your workspace's
    per-import limit.
  </Step>
</Steps>

## Where lead data comes from

* **Lead database.** Lead search and the first enrichment step query Topo's
  lead database: business profiles of professionals (name, headline, current
  and past job titles and employers, location, education, skills, languages,
  public profile URL, and follower count) and company records,
  compiled from third-party B2B data providers. It contains no special
  categories of personal data (GDPR Article 9) and no consumer data.
* **Enrichment.** `enrich_contact`, `get_and_enrich_contact`, and phone
  enrichment on import fill missing emails, phone numbers, and job details
  through FullEnrich, a third-party enrichment provider. Email addresses are
  verified before outreach.
* **Company research.** `enrich_account` and signals can read a company's
  public website and public company signals (funding, hiring, technologies).
* **Signals.** A signal checks one source once a day: public company facts
  (hiring, funding, news, technology adoption), people's job changes and
  public social media activity read through third-party data providers, or
  the workspace's own product events and CRM lists. It only imports into the list it owns, within
  the caps you set, and you can pause or archive it at any time.
* **AI variables with web search.** When an AI variable has web search on,
  computing a row searches the public web about that row's company or person
  through a web search provider.
* **Your own data.** Contacts you import, sync from your CRM, or add by hand
  stay in your workspace.

**Roles and legal basis.** The Topo customer who runs the outreach is the data
controller for the people it contacts and Topo acts as its processor under a
data processing agreement. For B2B prospecting in the EU, controllers
typically rely on legitimate interest (GDPR Article 6(1)(f)), which gives every
contacted person the right to object at any time (Article 21).

**Opting out and removal.**

* A person who replies to stop receiving messages is detected and added to the
  workspace's exclusion list as `UNSUBSCRIBED`, which stops every running
  sequence to them and blocks new ones for the duration set in the
  workspace's reply-exclusion settings (one year by default). Only a person in
  the Topo app can change that duration or lift the opt-out; the connector
  cannot.
* Anyone can ask Topo to access, correct, or delete the data held about them,
  or to be removed from Topo's lead database, by emailing
  [security@topo.io](mailto:security@topo.io). Requests are handled within 30
  days, as described in the [privacy policy](https://www.topo.io/consents/privacy-policy).

## Troubleshooting

| Symptom | What to do |
| - | - |
| Every call returns `unauthorized` | The sign-in expired or was revoked. Reconnect the connector to sign in again. |
| A tool returns a missing-scope error | The consent or API key does not cover that action. Reconnect and accept `mcp:write`, or use a key with the listed scope. |
| "This exclusion is an opt-out" | Expected: opt-outs can only be lifted by a person in **Settings → Organization → Exclusions**. |
| A lead search says it uses a legacy provider | That search was created before the current lead database. Open the link it returns in the Topo app, or create a new search. |
| `enroll` reports `queued_count` | Eligibility checks (email verification included) are still running. Enrollment finishes in the background and shows on the sequence in Topo. |
| The assistant sees an old tool list | MCP clients cache tool lists. Refresh or reconnect the connector. `upsert_contact` and `upsert_account` still answer under their old names. |
| "This playbook uses actions only the Topo app can run" | Expected: run or test that playbook from the Topo app. |
| Anything else | Contact [support](https://support.topo.io) with the time of the call and the tool name. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.