MCP server

Let an agent call the same operations through the Model Context Protocol.

The MCP server exposes the same five operations as tools. It forwards to the canonical V2 API, which remains authoritative for authentication, isolation, scopes, quota settlement, evidence, and replay. The MCP process stores no customer state.

Tools

Field	Type	Description
`validate_vat`	vat:validate	Validate one VAT registration and return the canonical result, evidence, freshness, and usage.
`search_companies`	company:search	Search one jurisdiction and return sourced, registry-qualified candidates with match reasons.
`resolve_company`	company:search	Resolve a live company name through the reviewed jurisdiction plan. Live-only.
`verify_company`	company:verify	Verify a jurisdiction, register, and registry identifier, with claim comparisons.
`discover_vat`	vat:discover	Discover sourced VAT associations for one entity; validation stays independent.

Streamable HTTP

Run the local HTTP transport and point an MCP client at it.

Local server

VAT_TOOLS_API_URL=http://127.0.0.1:4100 MCP_PORT=4200 pnpm --filter @vat-tools/mcp start:http

MCP client configuration

{
  "mcpServers": {
    "vat-tools": {
      "url": "http://127.0.0.1:4200/mcp",
      "headers": { "Authorization": "Bearer vat_REPLACE_WITH_A_SANDBOX_KEY" }
    }
  }
}

Local stdio

stdio configuration

{
  "mcpServers": {
    "vat-tools": {
      "command": "pnpm",
      "args": ["--dir", "/path/to/vat-tools", "--filter", "@vat-tools/mcp", "start:stdio"],
      "env": {
        "VAT_TOOLS_API_URL": "http://127.0.0.1:4100",
        "VAT_TOOLS_API_KEY": "vat_REPLACE_WITH_A_SANDBOX_KEY",
        "VAT_TOOLS_IDEMPOTENCY_KEY": "one-logical-operation-001"
      }
    }
  }
}

Idempotency and replay

Supply an Idempotency-Key header on an MCP call when the client supports per-request headers, and reuse the same key and tool input after an uncertain response. Keys are unique across operation kinds within an organization and environment.