Skip to content

MCP Server Setup

FirmaDB ships an MCP server alongside the REST API. Connect it to Claude Desktop, Cursor, or any MCP-aware client and your assistant gains six dedicated tools for European company data — no glue code, no function-calling boilerplate.

Beta

The MCP server is currently beta. Endpoint, transport, and tool catalog are stable, but tool descriptions and metadata may change. Pin the URL by environment, not by build date.

Connection details

Setting Value
URL https://mcp.firmadb.com/mcp
Transport Streamable HTTP
Protocol JSON-RPC 2.0
Auth Bearer token (restricted key, fdb_*_rk_*)
Wire format Fields named mcp.firmadb.com in your client config

The MCP server is a thin wrapper over the REST API — every tool call resolves to one or more api.firmadb.com requests internally. Rate limits, billing, and error envelopes are identical to the REST surface.

Use restricted keys, not secret keys

Always use rk class keys for agent integrations. Restricted keys can be scoped (specific operations, IP allowlist, country filter, expiry), so a leaked key has a small blast radius. Secret keys (sk) belong on your server and should never reach a client config file or model context.

Claude Desktop

Add a firmadb block to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "firmadb": {
      "url": "https://mcp.firmadb.com/mcp",
      "headers": {
        "Authorization": "Bearer fdb_live_rk_YOUR_KEY_HERE"
      }
    }
  }
}

Restart Claude Desktop. The six FirmaDB tools should appear in the tool selector.

Cursor

In Cursor's settings, open MCP Servers and add a new HTTP server:

{
  "name": "firmadb",
  "url": "https://mcp.firmadb.com/mcp",
  "headers": {
    "Authorization": "Bearer fdb_live_rk_YOUR_KEY_HERE"
  }
}

Generic MCP client

Any client that speaks Streamable HTTP MCP works. Point it at https://mcp.firmadb.com/mcp and pass the bearer token as an HTTP header. The server responds to the standard initialize, tools/list, and tools/call JSON-RPC methods.

curl -N -X POST https://mcp.firmadb.com/mcp \
  -H "Authorization: Bearer fdb_live_rk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The six tools

Tool Backed by What it does
firmadb_get_company GET /v1/companies/{country}/{registry_id} Exact lookup by registry ID
firmadb_search_companies GET /v1/companies/search Fuzzy name/address search with confidence scores
firmadb_verify_status GET /v1/companies/{country}/{registry_id} (compact projection) Compact KYB-friendly status check
firmadb_enrich_companies POST /v1/companies/lookup-batch Batch up to 100 rows per call
firmadb_check_coverage GET /v1/countries[/{code}] Check field availability per country
firmadb_estimate_cost GET /v1/account/usage + local calc Estimate cost & quota impact before running a job

Each tool's input schema and description are exposed via tools/list — your client surfaces them to the model automatically.

Pattern 1 — Search → Get

The single most common agent workflow:

1. firmadb_search_companies(q="Société Générale", country="FR")
2. inspect candidates, pick best by score
3. firmadb_get_company(country="FR", registry_id="914002639")

See Search → Lookup for the full walkthrough.

Pattern 2 — Estimate → Enrich

For batches over ~10 rows, always estimate first:

1. firmadb_estimate_cost(operation="enrich", estimated_records=500)
2. if human_approval_recommended → ask the user
3. split into chunks of 100
4. for each chunk: firmadb_enrich_companies(references=[...], idempotency_key=uuid())

See Cost Estimation and CRM Enrichment.

Pattern 3 — Coverage check before workflow

If you're about to operate on an unfamiliar country, check it first:

1. firmadb_check_coverage(country="CZ")
2. confirm needed fields are populated
3. proceed

See Country Coverage.

Pattern 4 — Error recovery from correction

FirmaDB errors are designed to be machine-actionable. When you get a 4xx, read correction and suggested_request before giving up:

1. firmadb_get_company(country="FR", registry_id="12345")
2. → 404 with correction: "SIREN must be 9 digits."
3. → suggested_request: {"country":"FR", "registry_id":"000012345"}
4. retry with suggested_request, then surface the result

See Errors for the full catalog.

Verifying your setup

Once connected, ask the model to run a smoke test:

Use firmadb_get_company to look up SOCIETE GENERALE: country FR, registry_id 552120222. Show me the name, status, and source_url.

If the assistant returns a real result with source_url pointing at annuaire-entreprises.data.gouv.fr, you're connected.

If you get an authentication error, verify:

  1. Header is Authorization: Bearer <key> (not bearer, not just <key>).
  2. Key starts with fdb_ and contains _rk_. Secret (_sk_) keys are not accepted.
  3. The key hasn't expired or hit its IP allowlist.

Troubleshooting

Symptom Likely cause Fix
Tools don't appear in client URL or header typo Re-check the JSON config; restart the client
401 unauthenticated Secret key used Generate a restricted (rk) key in the dashboard
403 insufficient_scope Restricted key missing required scope Add the scope or regenerate the key
429 rate_limit_exceeded Bursty calls Respect Retry-After; see Rate Limits
Tool times out Cold-start (rare) Retry once after 5s

What's next