> ## Documentation Index > Fetch the complete documentation index at: https://docs.topograph.co/llms.txt > Use this file to discover all available pages before exploring further. # Use Topograph from your AI agent > Connect Claude, ChatGPT, Cursor, VS Code and other AI agents to the Topograph MCP to look up companies in official business registers. **Early access** MCP 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](https://modelcontextprotocol.io) 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](/guides/topograph-mcp) 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](https://app.topograph.co/agents) (**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](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=Topograph\&connectorUrl=https%3A%2F%2Fmcp.topograph.co%2Fmcp) opens the form already filled in. To do it by hand: Open **Settings > Connectors > Add custom connector**. 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: ```bash theme={null} claude mcp add --transport http topograph https://mcp.topograph.co/mcp ``` To use an API key instead of signing in: ```bash theme={null} 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](/guides/topograph-mcp), 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 ``` Open **Settings > Apps & Connectors > Advanced settings** and enable **Developer mode**. Click **Create**. Name it `Topograph`, set the URL to `https://mcp.topograph.co/mcp` and the authentication to **OAuth**. Sign in with your Topograph account and choose the organisation. Developer mode is available on the plans where ChatGPT supports custom connectors. Workspace admins may need to allow it. [Add Topograph to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=topograph\&config=eyJ1cmwiOiJodHRwczovL21jcC50b3BvZ3JhcGguY28vbWNwIn0%3D) installs it in one click. Or add it to `~/.cursor/mcp.json`: ```json theme={null} { "mcpServers": { "topograph": { "url": "https://mcp.topograph.co/mcp" } } } ``` To use an API key, add a header that reads it from your environment: ```json theme={null} { "mcpServers": { "topograph": { "url": "https://mcp.topograph.co/mcp", "headers": { "Authorization": "Bearer ${env:TOPOGRAPH_API_KEY}" } } } } ``` [Add Topograph to VS Code](vscode:mcp/install?%7B%22name%22%3A%22topograph%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.topograph.co%2Fmcp%22%7D) installs it in one click. Or from a terminal: ```bash theme={null} 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. ```bash theme={null} 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. ```json Anthropic Messages API theme={null} { "mcp_servers": [ { "type": "url", "url": "https://mcp.topograph.co/mcp", "name": "topograph", "authorization_token": "" } ], "tools": [ { "type": "mcp_toolset", "mcp_server_name": "topograph" } ] } ``` ```json OpenAI Responses API theme={null} { "tools": [ { "type": "mcp", "server_label": "topograph", "server_url": "https://mcp.topograph.co/mcp", "headers": { "Authorization": "Bearer " }, "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 ` (preferred) or `x-api-key: `. Use the API key of a live environment (`sk_live_...`). Keys are on **Settings & More > Developer** in the [app](https://app.topograph.co). 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](/guides/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](/essentials/modes). ### Monitoring tools | Tool | What it does | | - | - | | `create_monitor` | Starts daily monitoring of a company, within your monitoring plan. Changes are delivered to your [webhooks](/essentials/monitoring). | | `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](https://app.topograph.co/agents) 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](/essentials/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](/guides/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 ```text theme={null} "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 The server could not identify you. With an API key, check that it is sent as `Authorization: Bearer ` 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`. 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. 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 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 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. 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`. ## Related * [Topograph Wizard](/guides/topograph-mcp): the integration helper for coding agents * [Verification vs onboarding mode](/essentials/modes) * [Coverage and pricing](/essentials/coverage-and-pricing) * [Development environments](/guides/development-environment) * [Monitoring](/essentials/monitoring) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.