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

# Topograph Wizard

> Give Claude Code, Cursor and other AI coding agents live Topograph coverage, pricing, docs and code samples while they build your integration.

<Note>
  **Beta.** The Topograph Wizard is in beta. Tools and behaviour may change during this period.
</Note>

Company data is complex: dozens of countries and US states, each with its own registers, identifiers, modes and data quirks. The Topograph Wizard plugs into your AI coding agent (Claude Code, Cursor, or any MCP-aware editor) so it pulls live coverage, pricing and integration methodology on demand. Ask questions in plain English, get grounded answers, and ship your integration in an afternoon.

The Wizard is an integration helper. It reads the public catalog and documentation and never runs a billed request. To look up actual companies from your agent, use the [Topograph MCP](/guides/mcp) instead.

<Tip>
  **Two commands and you're in.** In Claude Code:

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

  The plugin installs both servers: the Wizard and the [Topograph MCP](/guides/mcp) for company data. Run `/mcp` and sign in with Topograph the first time.
</Tip>

The Wizard's address is `https://mcp.topograph.co/wizard`. It used to be called the Designer MCP, at `https://api.topograph.co/designer-mcp`; that address keeps working, so existing setups need no change.

## What you can ask

These prompts work today and call the right tools and rules under the hood:

```text Sample prompts theme={null}
"Does France have UBO data? What about Italy and the UK?"

"How do I authenticate? Walk me through getting an API key
 and making my first call."

"What's the difference between prefill mode and verification
 mode, and when do I use each?"

"What does Topograph cover in Germany for company + UBOs,
 and what response fields will I get back?"

"Write me a Node.js example that searches a French company,
 then fetches its profile with progressive results."

"How do I handle webhooks for /v2/company? Which event tells
 me a request is fully done?"

"I'm a fintech reselling Topograph KYB to my customers. How
 do I attribute usage per end-client for rebilling?"

"How do I test my integration end-to-end without hitting real
 registers?"

"What's the canonical KYB onboarding flow with Topograph,
 from signup search to compliance record?"

"How do I cap a single /v2/company request so a deep
 ownership graph stays within a known bound?"
```

Each answer is grounded in live data from the Topograph catalog and the canonical integration rules, not in training data that may be months out of date.

## Why it's better than reading docs

<CardGroup cols={2}>
  <Card title="Live country catalog" icon="globe">
    Coverage, identifiers, datapoints, legal forms, roles, and pricing are pulled live from the catalog. You'll never get an answer based on stale documentation.
  </Card>

  <Card title="Methodology built in" icon="route">
    The Wizard ships with the canonical patterns: search-first identifier resolution, prefill vs verification phasing, webhook terminal detection, budget caps, and more.
  </Card>

  <Card title="Code that compiles" icon="code">
    Example snippets are derived from the OpenAPI spec. No hallucinated endpoint paths, no fabricated request shapes.
  </Card>

  <Card title="Grounded in your editor" icon="window">
    Your agent works alongside your existing code: pull data, write the integration, run it, iterate. No copy-pasting from a docs tab.
  </Card>
</CardGroup>

## Country-specific integration data

Call `get_country` with the country code (for example, `{"cc":"FR"}`) to retrieve its public manifest. The same manifest is available through the `topograph://countries/FR` resource. Use it when mapping a country into your own model; use `get_openapi` with `path: "/v2/company"` and `includeSchemas: true` for the company API response schema. Country-specific manifest fields include:

* `identifiers`: accepted identifiers, their formats and examples, whether they are primary or searchable, and the matching `company.identifiers` response key when Topograph returns one.
* `activityCodes`: `responseKeys` lists revision-specific `company.activities` keys with their versions, `isLatest`, and `supersedes`. `unversionedKeys` lists keys whose revision is unknown, with a reason. Legacy aliases are not enumerated here.
* `enums`: maintained country enum sets: `legalForms`, `legalFormsOnboarding`, `roles`, `companyStatuses`, `registerCourts` (local courts or offices), and `registerTypes` (register sections).
* `complianceSignals`: register-reported compliance flags and statutory-filing fields available for the country.
* `registers` and `dataBlocks`: public register descriptions, supported datapoints, entity types, modes, and their applicability notes.
* `countryDocuments`: document types and names, including `subType` and `appliesTo` where supplied. `subType` matches the response item's `subType`. `otherDocuments` lists additional document names and descriptions.
* `developmentStatus` and `availableOnRequest`: integration maturity and capabilities available on request, where listed.
* `performance`: indicative search, datapoint, and document timings. Datapoint timings describe source speed, not end-to-end request turnaround.

Each enum set contains `values` and `sources`. Legal forms and roles include `code`, `source` (the code system), `localName`, `standardized`, and optionally `englishName`. Legal forms may include `iso20275Code` and `isDiscontinued`. Roles include `isLegalRepresentative` and `isOtherKeyPerson`, and may include `iso5009Mappings` with `oorCode`, `elfCode`, and optional `legalBasis`. A role can have several ISO mappings depending on the legal form; match `elfCode` to the legal form's `iso20275Code` where available.

`companyStatuses.values` contains strings. `registerCourts.values` contains `localName`, which can form part of a registration identifier. `registerTypes.values` contains `code`, `localName`, and optionally `englishName` and `scope`. Identifier `appliesTo` and `activityCodes.local[].appliesTo` describe the entity types to which an entry applies; when omitted, the entry applies to all covered entity types.

In `complianceSignals`, `flags.values[].kind` identifies a `company.complianceFlags` entry. `reportsNegative: true` means the register can explicitly report `active: false`; absence is not the same as a negative result. `statutoryFilings.values[].kind` identifies an entry in `company.statutoryFilings`, and `fields` lists relative paths such as `lastFiled.filedOn`. Optional `cadence` and `note` explain its filing cycle and limitations.

Data-block modes describe `fast`, `authoritative`, datapoint subsets, caveats, and routing notes. Their source references identify entries in `registers`; consult per-datapoint details and routings as well as defaults. A `cached` flag describes a non-authoritative cached mode, not a freshness guarantee. A block's `requiredCredential` identifies the public register credential `sourceKey` and whether it is mandatory for that fetch or enhances completeness. See [register credentials](/essentials/register-credentials) for setup and fallback behavior.

`legalForms` describes verification values. When `legalFormsOnboarding` is absent, use `legalForms` for all modes. When present, it supplies the prefill-specific values. Read the provenance in `sources` for scope and completeness: some sets contain observed values rather than an exhaustive closed list.

```text theme={null}
"For France, list the identifiers and response keys, activity-code keys,
 legal forms, company roles, and company statuses I need to map."
```

An absent optional field does not by itself prove the underlying company data is unavailable. For example, an identifier without `key` may be accepted for lookup but not echoed in `company.identifiers`. Consult the field-specific meaning and country coverage. `list_countries` only returns summaries, and `find_data` does not search enum values or identifier keys; use `get_country` for these mappings.

## When the Wizard earns its keep

Use it when you would otherwise be context-switching to docs:

* Onboarding a country you've never integrated before
* Sizing volume against country coverage and capability
* Designing async delivery (webhooks vs polling, terminal-event detection)
* Picking the right datapoint mix for KYB vs onboarding flows
* Debugging "why am I getting this error / why is this datapoint missing?"
* Reviewing an existing integration against the canonical methodology
* Writing tests against a development environment (or the deprecated TEST country)

For one-off questions, the regular docs are still the right tool. For real integration work, the Wizard is faster.

## What's inside

Tools your agent will call:

* `list_countries`, `get_country`, `find_data`: live country and capability catalog.
* `get_pricing`: public per-country prices for any data block.
* `search_docs`, `get_doc`: search and fetch documentation pages.
* `get_openapi`: endpoint definitions straight from the OpenAPI spec.
* `example_snippet`: copy-paste snippets in curl, Node, Python, or Go.
* `whoami`, `my_pricing_simulations`, `personalized_quote`: pricing simulator quotes tied to your Topograph login.

Built-in integration rules your agent reads:

* Onboarding methodology: the five-step KYB flow from search to audit.
* Search-first resolution: turning fuzzy user input into a canonical company ID.
* Prefill vs verification mode: picking the right one per call.
* Webhooks: signed delivery, progressive payloads, terminal-event detection.
* Workspaces: required for resellers, end-client attribution and rebilling.
* Budgets: `maxBudget`, `profileMaxBudget`, `graphMaxBudget`.
* TEST country (deprecated): magic identifiers for deterministic testing.
* Data blocks, documents, common pitfalls, and country coverage matrix.

## Install: other clients

If your client supports HTTP MCP servers and OAuth discovery, point it at the endpoint directly:

```json theme={null}
{
  "mcpServers": {
    "topograph-wizard": {
      "type": "http",
      "url": "https://mcp.topograph.co/wizard"
    }
  }
}
```

In Claude Code without the plugin:

```bash theme={null}
claude mcp add --transport http topograph-wizard https://mcp.topograph.co/wizard
```

Your client will prompt you to sign in with Topograph the first time it queries the Wizard. Any Topograph login works, and no API key is needed: the Wizard only reads the public catalog and your own pricing simulations. Your application still calls the Topograph API with its own API key, and the [Topograph MCP](/guides/mcp) uses your organisation's access when your agent looks up companies.

## Public repository

The plugin, with both the Wizard and the Topograph MCP, is published from the public marketplace repository:

[github.com/getsemaphore/topograph-mcp-library](https://github.com/getsemaphore/topograph-mcp-library)

The source is mirrored from Topograph's monorepo on every release.

## Related

* [Use Topograph from your AI agent](/guides/mcp): the Topograph MCP for company data
* [Quickstart](/quickstart)
* [Coverage and pricing](/essentials/coverage-and-pricing)
* [Verification vs prefill mode](/essentials/modes)
* [Webhooks](/guides/webhooks)
* [Workspaces](/essentials/workspaces)
* [Development environments](/guides/development-environment) (the TEST country is deprecated)

Country manifests include `complianceSignals.flags.values`: covered compliance flag keys, country-specific descriptions, source registers, reported fields, negative-answer semantics, and request paths (`providedBy`). Search flag keys or their descriptions with `find_data`. `get_pricing` includes country coverage and filters covered flags to the requested catalog item when a SKU is supplied. Country resources and `get_country` expose the same country-owned metadata.


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