Skip to main content
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.
  • 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

1

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.
2

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.
3

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.
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

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. 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.
1

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.
2

Refine

refine_lead_search applies one change at a time (“remove France”, “only over 100 employees”) and returns the updated summary.
3

Preview (optional)

preview_lead_search samples up to 25 matching leads cheaply, to check the filters before a full run.
4

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.
5

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.

​
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. Requests are handled within 30 days, as described in the privacy policy.

​
Troubleshooting