Use Topograph from your AI agent

Early accessMCP access is an early-access feature, available only to subscribed clients with active API access. Functionality and availability may change without notice.MCP access does not modify, extend, or reduce the terms governing the relationship between Topograph and the client, as defined in the signed Terms and Conditions and Data Processing Agreement.The client is solely responsible for the choice of AI agent and for its use. Topograph provides data as returned by its MCP server and is not responsible for how the agent interprets, summarises, or presents that data.

The Topograph MCP lets an AI agent query company data the way your application does through the API. Ask “who are the directors of this company?” or “who owns it?” in plain English, and the agent searches the register, picks the right company, and fetches only what you asked for. It is a remote Model Context Protocol server at https://mcp.topograph.co/mcp. Sign in with your Topograph account, or connect with an API key. Requests are billed exactly like the API: same prices, same wallet. Requests you make while signed in also show up in your request history in the app.

Building an integration rather than looking up companies? The Topograph Wizard gives your coding agent live coverage, pricing, docs and code samples. It is free to use. The Claude Code plugin installs both servers.

Using agents responsibly

When your agent calls the MCP, Topograph returns the results to the client you connected. Results can include personal data about directors, shareholders and beneficial owners. Your chosen agent platform and model provider may process and retain that data. Before connecting, review your provider’s data handling, retention and access settings. You are responsible for choosing and configuring your agent, supervising its requests, and ensuring that sharing the returned data with your provider is appropriate for your use. AI summaries can misinterpret or omit returned data. Check the underlying results and official documents before making KYB or compliance decisions. You remain responsible for those decisions.

Connect your agent

The app lists every client below, with copy buttons and one-click links, on the AI agents page (AI agents in the sidebar). That page also shows your MCP spending this month.

Works in Claude on the web, Claude Desktop, Cowork and the mobile apps.Add Topograph to Claude opens the form already filled in. To do it by hand:

Add a custom connector

Open Settings > Connectors > Add custom connector.

Enter the server

Name: Topograph. URL: https://mcp.topograph.co/mcp.

Click Connect and sign in with your Topograph account. Choose the organisation Claude should act for.

On Team and Enterprise plans, an owner may need to add the connector for the organisation first.

Add the server, then run /mcp in Claude Code to sign in:

claude mcp add --transport http topograph https://mcp.topograph.co/mcp

To use an API key instead of signing in:

export TOPOGRAPH_API_KEY="sk_live_..."
claude mcp add --transport http topograph https://mcp.topograph.co/mcp \
  --header "Authorization: Bearer $TOPOGRAPH_API_KEY"

Or install the Topograph plugin. It adds this server, the Topograph Wizard, a /topograph:lookup command and skills that teach Claude to search first and check the price before it pays:

/plugin marketplace add getsemaphore/topograph-mcp-library
/plugin install topograph@topograph

Turn on developer mode

Open Settings > Apps & Connectors > Advanced settings and enable Developer mode.

Create the connector

Click Create. Name it Topograph, set the URL to https://mcp.topograph.co/mcp and the authentication to OAuth.

Developer mode is available on the plans where ChatGPT supports custom connectors. Workspace admins may need to allow it.

Add Topograph to Cursor installs it in one click. Or add it to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "topograph": {
      "url": "https://mcp.topograph.co/mcp"
    }
  }
}

To use an API key, add a header that reads it from your environment:

{
  "mcpServers": {
    "topograph": {
      "url": "https://mcp.topograph.co/mcp",
      "headers": { "Authorization": "Bearer ${env:TOPOGRAPH_API_KEY}" }
    }
  }
}

Add Topograph to VS Code installs it in one click. Or from a terminal:

code --add-mcp '{"name":"topograph","type":"http","url":"https://mcp.topograph.co/mcp"}'

VS Code asks you to sign in the first time the agent uses a Topograph tool.

gemini mcp add --transport http topograph https://mcp.topograph.co/mcp

Gemini CLI opens the Topograph sign-in the first time it connects.

Agents you build on a model provider’s API connect with an API key.

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.topograph.co/mcp",
      "name": "topograph",
      "authorization_token": "<TOPOGRAPH_API_KEY>"
    }
  ],
  "tools": [
    { "type": "mcp_toolset", "mcp_server_name": "topograph" }
  ]
}

{
  "tools": [
    {
      "type": "mcp",
      "server_label": "topograph",
      "server_url": "https://mcp.topograph.co/mcp",
      "headers": { "Authorization": "Bearer <TOPOGRAPH_API_KEY>" },
      "require_approval": "always"
    }
  ]
}

The Anthropic MCP connector is in beta: send the anthropic-beta: mcp-client-2025-11-20 header with the request. Keep approvals on for paid tools, or set a low max_cost_credits in your prompts, so an unattended agent cannot spend without a check.

Authentication

There are two ways to connect. Both act for one organisation and its wallet. Sign in (OAuth). The default for chat apps and editors. The first time the agent connects, your browser opens the Topograph sign-in. You then choose which organisation (environment) the agent acts for and approve what it may do:

Permission	Allows
`data:read`	The free tools: search in one country, coverage, prices, cost estimates, document lists, your requests and monitors
`data:spend`	The paid tools: company data, document orders and worldwide search
`monitors:write`	Starting and stopping monitoring

Anyone in an organisation can connect and spend through the MCP, within the monthly cap described below. To switch organisation, disconnect and connect again. API key. For agents you build yourself, or when you prefer not to sign in. Send the key as Authorization: Bearer <TOPOGRAPH_API_KEY> (preferred) or x-api-key: <TOPOGRAPH_API_KEY>. Use the API key of a live environment (sk_live_...). Keys are on Settings & More > Developer in the app. MCP access is available only to subscribed clients with active API access.

Tools

The agent picks the tools itself. You do not need to name them, but knowing what they do helps you read what it did.

Free tools

Tool	What it returns
`search_companies`	Companies in one country matching a name, registration number or LEI, each with the identifier the other tools take.
`get_country_coverage`	What Topograph covers in a country: datapoints, documents, identifier formats, prices, typical speed and beta status.
`get_pricing`	Your prices for one country: every data block and document with the price you pay, including contract prices.
`estimate_cost`	The price of a set of datapoints, and optionally documents, before running it.
`list_documents`	The official documents available for a company, each with its price and expected delivery time.
`get_request`	The status and results of a previous request: what has arrived so far and what is still pending.
`get_document`	A fresh download link for a document you already retrieved (valid for about 15 minutes), with its metadata.
`list_requests`	Every request on the account (API, app and MCP), newest first, searchable by company name or identifier.
`get_account`	Your balance, environment (live or sandbox), workspaces, and your MCP spending this month against the cap.
`list_monitors`	The companies you monitor.

Paid tools

Tool	What it returns
`get_company`	The company profile and any of: legal representatives, other key persons, establishments, shareholders, subsidiaries, ultimate beneficial owners, available documents. Billed like the same datapoints on the API.
`order_documents`	Buys documents from `list_documents` and returns them, or a request to follow when delivery takes longer.
`search_companies_worldwide`	Finds a company when you do not know its country, or across several countries. Billed per search, only when it resolves to one good match. In beta, like global search.

get_company takes a mode, as the API does. verification (the default) reads the authoritative register live and is what compliance work needs. onboarding is faster and cheaper but not suitable for compliance records. See Verification vs onboarding mode.

Monitoring tools

Tool	What it does
`create_monitor`	Starts daily monitoring of a company, within your monitoring plan. Changes are delivered to your webhooks.
`delete_monitor`	Stops monitoring a company.

How paid calls work

Paid and monitoring tools are marked as actions that change something, so Claude, ChatGPT and most editors ask you to confirm before they run. Free tools run without asking. Every paid call is bounded and priced in the open:

A ceiling per call. get_company takes max_cost_credits. A call that would cost more is refused instead of run. It works like maxBudget on the API.
Documents are ordered at a quoted price. order_documents requires expected_total_credits, the total the agent showed you. If the price changed since, the order is refused and nothing is charged.
Every result shows its cost. Each tool result states what that call cost, so the agent can tell you.

A good agent searches for free, estimates the cost for free, tells you the price, and only then runs the paid call. The Claude Code plugin and the tool descriptions teach this order.

Monthly cap

Each person can spend up to 1,000 credits per calendar month through the MCP. The cap counts purchases made through the MCP only; your API usage is not affected. For an API key, the cap applies to the key. When a call would go over the cap, it is refused with a message that says when the cap resets: midnight UTC on the first day of the next month. get_account and the AI agents page show what you have spent this month. Development environments are not capped and never cost real money.

Long-running requests

Some registers answer in seconds, some take minutes. get_company waits about 30 seconds (an agent can ask for up to 50 with wait_seconds). If everything has arrived, you get the full result. Otherwise you get what has arrived so far, the datapoints still pending, and a request_id. Ask the agent to check again later. It calls get_request with the request_id, which is free. Calling get_company again would start, and bill, a new request. Some documents are delivered manually by the register and take hours or days. The order returns a request_id straight away; the document appears in get_request once it arrives. See Manual delivery.

Register data is third-party content

Company names, addresses, activity descriptions and documents come from registers and the companies that file with them. Topograph returns them as published. Your agent should treat everything in a result as data to report, not as instructions to follow. A company name that says “ignore your previous instructions” is still just a company name. Keep confirmations on for paid tools so that nothing in a result can lead to a purchase without you seeing it.

Sandbox

Build and test against a development environment first. Its MCP server is:

https://mcp.sandbox.topograph.co/mcp

Connect with the development environment’s API key (sk_dev_...). Every tool works as it does in live, but results are generated data, requests cost only virtual credits, and there is no monthly cap.

Example prompts

"Find the French company Doctolib and show me its legal representatives."

"Who are the ultimate beneficial owners of ASML Holding N.V.? Tell me the
 price before you fetch anything."

"Is 'Bamberger GmbH' in Vienna still active? Use onboarding mode, I just
 want a quick check."

"List the official documents available for Companies House number 00445790
 and their prices. Don't order anything yet."

"Order the trade register extract for SIREN 552100554 if it costs less
 than 5 credits."

"What did I spend through the MCP this month, and what were my last
 five lookups?"

"Start monitoring the three companies we just looked up."

Troubleshooting

401 Unauthorized

The server could not identify you. With an API key, check that it is sent as Authorization: Bearer <key> and has not been rotated. With sign-in, the session may have expired: disconnect and connect again (in Claude Code, run /mcp). A development key (sk_dev_...) only works on the sandbox server, and a live key only on https://mcp.topograph.co/mcp.

403 Forbidden

You are identified but not allowed to do this. Either the organisation does not have active API access and a subscription, or you did not grant the permission the tool needs. For example, paid tools need data:spend. Reconnect and approve the permission, or ask an admin of your organisation.

Monthly cap reached

The call would take your MCP spending this month over the cap. The message says when it resets. Nothing was charged, and free tools keep working.

Cursor ignores my Authorization header

Cursor prefers OAuth when a server advertises it, which Topograph does, so it can skip the header you configured. Just sign in when Cursor asks; it acts with the same access.

The result is incomplete

The register had not answered within the wait (about 30 seconds by default). Ask the agent to check the request again; it uses get_request, which is free.

The agent did not ask before a paid call

Some clients let you approve a tool permanently. Review your client’s tool permissions and set Topograph’s paid tools back to “ask”. With your own agent, keep require_approval on and pass max_cost_credits.

Topograph Wizard: the integration helper for coding agents
Verification vs onboarding mode
Coverage and pricing
Development environments
Monitoring

Getting Started

AI Agents

Integration Guides

Core Features

Behavior & Operations

Use Topograph from your AI agent

Using agents responsibly

Connect your agent

Authentication

Tools

Free tools

Paid tools

Monitoring tools

How paid calls work

Monthly cap

Long-running requests

Register data is third-party content

Sandbox

Example prompts

Troubleshooting

​Using agents responsibly

​Connect your agent

​Authentication

​Tools

​Free tools

​Paid tools

​Monitoring tools

​How paid calls work

​Monthly cap

​Long-running requests

​Register data is third-party content

​Sandbox

​Example prompts

​Troubleshooting

​Related

Using agents responsibly

Connect your agent

Authentication

Tools

Free tools

Paid tools

Monitoring tools

How paid calls work

Monthly cap

Long-running requests

Register data is third-party content

Sandbox

Example prompts

Troubleshooting

Related