MCP servers

The Model Context Protocol is how a model in the loop — a chat assistant, a copilot, an internal tool, an autonomous AI — calls tools. MasterDB offers it on two surfaces for AI companies:

Surface	Where	Key	Billed
`masterdb-mcp`, self-hosted — production	runs in your own network, beside your model	your retrieval key, in your process	yes, exactly as the raw API
Hosted public	`https://mcp.masterdb.ai/v1/mcp/public`	none	nothing billable

Businesses have their own hosted server; see MCP for businesses.

Why MasterDB never hosts a billable MCP server

MCP’s own authentication is an OAuth bearer token. A MasterDB-hosted server for billable calls would bring bearer tokens back into production, remove the signed request that is the other half of every receipt, and put MasterDB in the middle of every call your AI makes. So in production your key never leaves your company: you run masterdb-mcp, and every tool call becomes an RFC 9421-signed request from your process to the retrieval API. Receipts, billing, blocking, terms, rate limits and non-repudiation are byte for byte those of the raw API, and there is no MasterDB hop between your model and MasterDB.

Use MCP when a model decides what to ask. When your own code composes the queries — a retrieval layer, query templates, a search box — use the SDK. Both are the same signed request underneath, and you can use both.

Install and run

Apache 2.0, Node 24 or later, built on the official MCP SDK; the client and server negotiate the protocol version.

npm install -g @masterdb/mcp
export MASTERDB_RETRIEVAL_KEY="$(cat retrieval-key.jwk)"   # or name a key file in the configuration
export MASTERDB_COUNTRY=US                                  # your users' country, when a search names none
masterdb-mcp --check      # validates the configuration and prints the key id it signs with
masterdb-mcp              # stdio: what an MCP client starts

Try it against the sandbox first: take a sandbox key in the AI Portal (The sandbox) and set "environment": "sandbox". A sandbox key is never accepted by production, and a production key never by the sandbox. Set the grant the portal answered with the key as sandbox_key_grant (or MASTERDB_SANDBOX_KEY_GRANT): masterdb-mcp sends it as the MDB-Sandbox-Key header on every request, and the sandbox admits your key on the first one. Without it that first request is refused 401 key_unknown.

Connecting a client

Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json) start the server as a process:

{
  "mcpServers": {
    "masterdb": {
      "command": "masterdb-mcp",
      "args": ["--config", "/etc/masterdb/mcp.json"]
    }
  }
}

Claude Code:

claude mcp add masterdb -- masterdb-mcp --config /etc/masterdb/mcp.json

Configuration

A JSON file named by --config or MASTERDB_MCP_CONFIG, validated against the published schema (masterdb-mcp --print-config-schema). Every member can be overridden from the environment. The private key is never in the file — the file says where it is.

{
  "version": 1,
  "environment": "production",
  "key": { "file": "/run/secrets/masterdb-retrieval-key.jwk" },
  "country": "US",
  "anchors_file": "/etc/masterdb/anchors.json",
  "verify_online": false,
  "timeout_ms": 10000,
  "retry": { "max_attempts": 3, "max_delay_ms": 5000 },
  "transport": { "type": "stdio" }
}

Member	Environment variable	Default
`environment`	`MASTERDB_ENVIRONMENT`	`production` (or `sandbox`)
`api_base_url`	`MASTERDB_API_URL`	`https://api.masterdb.ai` / `https://sandbox.api.masterdb.ai`
`public_base_url`	`MASTERDB_PUBLIC_URL`	`https://verify.masterdb.ai` / `https://sandbox.api.masterdb.ai`
`source_line_base`	`MASTERDB_SOURCE_LINE_BASE`	`https://verify.masterdb.ai` / `https://sandbox.verify.masterdb.ai` (the verify host a source line points to)
`key.file` or `key.env`	`MASTERDB_KEY_FILE`	`key.env` = `MASTERDB_RETRIEVAL_KEY`
`country`	`MASTERDB_COUNTRY`	none: a search must then name its country
`sandbox_key_grant`	`MASTERDB_SANDBOX_KEY_GRANT`	none; sandbox only: the grant (`mdb_sbxk1.…`) the AI Portal answered with the sandbox key, sent as `MDB-Sandbox-Key` on every request; refused with `production`
`anchors_file`	`MASTERDB_ANCHORS_FILE`	none: `verify` then claims nothing
`verify_online`	`MASTERDB_VERIFY_ONLINE`	`false`
`transport.type`	`MASTERDB_MCP_TRANSPORT`	`stdio`
`transport.host`, `.port`, `.path`	`MASTERDB_MCP_HOST`, `_PORT`, `_PATH`	`127.0.0.1`, `8787`, `/mcp`
`transport.bearer_token_env`	`MASTERDB_MCP_BEARER_TOKEN_ENV`	required when the host is not loopback

The key is the private half of a retrieval key registered in the AI Portal (a sandbox key taken there, for the sandbox) — Ed25519 (the default) or P-256 — as a private JWK or a PKCS #8 PEM, from a file or an environment variable. It is read once at start and held only inside the signer: never logged, never returned by a tool, never sent. An error names where the key was looked for, never what was there.

Streamable HTTP ("transport": {"type": "http"}) is for a fleet where the model runs apart from the process holding the key; one MCP session is one conversation. The server signs with your key for anyone who can reach it, so it listens on loopback by default, requires its own bearer token on any other address, and refuses browser origins you have not allowed.

Tools, resources and prompts

Tool	Calls	Does
`search_products`, `search_business_files`, `search_events`, `search_jobs`, `search_updates`	`POST /v1/{collection}/search`	One search tool per collection, each typed with exactly its fields, operators and sort keys — generated from the same allow-lists as the API (Fields, filters and sort keys). One country, a mandatory sort, at most 50 rows.
`fetch`	`GET /v1/records/{id}`	One record exactly as sealed, with its seal, sidecar, sealed AI policy, provenance and receipt.
`verify`	the verifier library; `POST /v1/verify`	Checks what came back: row signatures, the receipt, the sidecar, and — online — the business’s seal and its AI policy’s seal, with MasterDB’s signed statement.
`receipts`	`GET /v1/receipts`	Your own receipts, by window, key or legal entity; or one checked.
`ai_policy`	— (local)	What a business permits and the contexts it blocks, from a row’s `ai_policy_bits` or a fetched record’s sealed AI policy, in plain words.
`terms`	`GET /v1/terms`	The AI-company Terms, current or by version.
`ai_policy_key`	`GET /v1/ai-policy-key`	The key to the AI policy bits (public server).
`usage`	`GET /v1/usage`	Your usage.
`ads_pool`	`POST /v1/ads/pool`	Up to 20 ads for the user’s country and a few subject keywords, in the order the model states; each with a render token.
`report`	`POST /v1/ads/render`, `/v1/ads/click`	Your signed statement back to MasterDB: `ad_render` (an ad’s render token, or a sponsored search row by its search’s `retrieval_id` and the `record_id`, with the format) answers a click token and the label to show; `ad_click` confirms a click with that token.

Resources: masterdb://terms/{version}, masterdb://certificate/{business_uuid}, masterdb://projection/{type}/{version}, masterdb://vocabularies/{name}, masterdb://spec. Prompts: answer_with_source_line and render_sponsored_item, the source-line and render conventions. There is deliberately no catalogue, list or bulk resource: the anti-enumeration rules hold on every transport.

Sponsored items. Call ads_pool, show what you choose with its label, then report ad_render for each one shown; when the user clicks, report ad_click with the click token (within 24 hours). A sponsored row in a search result is confirmed the same way, with the search’s retrieval_id. MasterDB is never in the redirect path: send the person to the destination yourself. Ads and sponsored items has the rules: labels, windows, repeats and what never to do.

What the model sees

Rows and records exactly as served. A tool result’s first block is MasterDB’s response body, byte for byte: nothing is parsed and re-serialised, so a record’s bytes still hash to its seal. The second block, labelled masterdb_mcp_notes, is the server’s reading: the terms in plain words, the source line, the receipt’s retrieval_id, whether the call was billable (never in the sandbox, which bills nothing).
The fix in every refusal. A search is validated in your process with the retrieval service’s own compiler before anything is sent. A bad one is answered with the API’s RFC 9457 problem and the fix — sort_required with the valid sort keys, unknown_field with the nearest valid name — so the model corrects itself in one turn, with no request sent and nothing billed.
Two things the model does not guess. The user’s country comes from the conversation — your framework sets masterdb.ai/country in the tool call’s _meta — or from the configuration; a country the model names itself is an explicit override. The session_ref is generated per conversation, or taken from _meta masterdb.ai/session_ref, and is never shown to the model.
Data, never instructions. Text in a record is the business’s statement. The server never acts on it and never alters it: a record that contains an instruction aimed at an AI comes back verbatim, as data, like every other string. MasterDB guarantees that text cannot reach beyond the business that published it; defending your model against what it reads is yours (security model).

Requests, nonces and retries

Every request is signed as Signing requests describes, with a fresh single-use nonce; the server keeps every nonce it signed with until the signature expires, so none is reused. It retries only what MasterDB did not serve: 429 and 503 after Retry-After (up to max_delay_ms), 502 and 504, and a connection that failed before the request was sent — each attempt signed afresh. A request that timed out after it was sent is never retried: it may have been served and billed.

Verifying

verify trusts MasterDB’s key set only when it chains to the root anchors in anchors_file (the sandbox’s anchors for the sandbox); without anchors it says plainly that nothing was verified. The key set is refreshed every ten minutes, so MasterDB’s key rotations arrive with no change on your side. The business’s key register is MasterDB’s, so the seal check itself is online (verify_online, or online: true on the call), and MasterDB’s answer is a statement signed by its statement key, which the server checks.

The hosted public server

It speaks MCP’s Streamable HTTP transport at one endpoint. The initialize answer carries an Mcp-Session-Id: send it on every later request of the conversation. A session is bound to the credential that opened it and ends after 30 minutes idle. There is no server-initiated stream (GET answers 405); DELETE with the session id ends a session. The client must accept both application/json and text/event-stream. The endpoints are in the reference.

Public — POST https://mcp.masterdb.ai/v1/mcp/public. The public verification reads only: verify, certificate, keys, projection, spec, log_checkpoint, log_proof and vocabularies. No credential, nothing billable, and no search or fetch. Rate-limited per address generously, so as never to block a checker.