Authoring MCP tools for verification data sources

When an operator attaches one of your MCP tools as a “lookup tool” in the workspace’s Identity & Verification panel, the platform’s verification specialist will call it during KBV flows and ask the caller a question whose answer depends on its result. This page describes the contract your tool needs to meet.

The contract in one paragraph

The platform calls your tool with the caller’s contact_id (or account_id) and reads the result. The LLM forms a question whose correct answer is derivable from the result. The caller’s reply is compared back to the result. There is no specific JSON shape your tool must return — the LLM is flexible — but the shape should reliably yield a small set of unambiguous, recently-knowable facts about the contact.

Three data categories

The operator tags your tool with one of three categories when attaching it. The category determines when the verification specialist will prefer your tool over others (NIST §5.3.2 ordering: transaction history > account state > customer profile).

transaction_history

Returns recent events: orders placed, payments made, refunds issued, deliveries, support interactions. Strongest verification signal because an attacker rarely knows what the caller did in the last 30 days.

Good response shape:

{
  "items": [
    { "id": "ord_abc", "type": "order", "amount": 12.50, "currency": "EUR", "ordered_at": "2026-04-12T10:00:00Z", "delivered_at": null, "items": [{ "sku": "SKU-123", "name": "Blue widget", "quantity": 2 }] },
    { "id": "ord_xyz", "type": "order", "amount": 47.00, "currency": "EUR", "ordered_at": "2026-04-05T14:00:00Z", "delivered_at": "2026-04-08T11:00:00Z", "items": [...] }
  ],
  "as_of": "2026-05-13T09:00:00Z"
}

The LLM can ask “what’s the most recent order you placed?”, “roughly how much was your last order?”, “what date did your last order arrive?”. All three are derivable from the response.

account_state

Returns the current state of the caller’s account: balance, active subscriptions, last login, current credit. Medium-strength signal.

Good response shape:

{
  "balance": { "amount": 142.10, "currency": "EUR" },
  "active_subscriptions": [{ "name": "Premium", "renews_at": "2026-06-01" }],
  "last_login_at": "2026-05-12T22:30:00Z",
  "as_of": "2026-05-13T09:00:00Z"
}

The LLM can ask “what’s your account’s currency?”, “do you have a subscription that renews next month?”, “when did you last log in?”. The first is trivial; the others are recall-friendly without being guessable.

customer_profile

Returns longer-lived demographic fields: date of birth, postal address, mother’s maiden name (yes, really), preferred language. Weakest signal because OSINT often surfaces these.

Good response shape:

{
  "first_name": "Alex",
  "last_name": "Smith",
  "date_of_birth": "1985-07-14",
  "postal_address": { "line1": "Hauptstrasse 12", "city": "Berlin", "postcode": "10115", "country": "DE" },
  "preferred_language": "de"
}

The LLM can ask “what’s the postal code on file?”, “what’s your preferred language for communication?”. Use sparingly — pair with at least one stronger category for meaningful confidence.

Required tool arguments

The platform passes one of two arguments depending on whether your tool is account-scoped:

{ "tenantId": "...", "workspaceId": "...", "contact_id": "<uuid>" }

or:

{ "tenantId": "...", "workspaceId": "...", "account_id": "<uuid>" }

tenantId and workspaceId are always present (mcp-hub injects them). The third field comes from the caller’s resolved contact. If your tool’s inputSchema requires fields beyond these — e.g. date_from — the LLM will fill them in based on context (typically asking for “the last 30 days” of transactions).

Return shape guidance

Return the smallest payload that meaningfully answers the questions a caller can recall. Avoid:

• Raw IDs without human-readable labels. The caller doesn’t know what ord_abc123def is; the LLM will struggle to form a question about it. Pair every ID with a name, date, or amount.
• Hundred-item lists. Three to five items is the sweet spot. If your underlying system can return more, paginate or limit.
• PII the LLM will be tempted to read back verbatim. Don’t include the caller’s IBAN, full card number, or government ID number in a lookup tool’s response. The platform’s rejection-language guidelines suppress most of this, but a response can be cited unintentionally if the LLM thinks it’s the answer to the question.

Risk classification

The operator separately sets a risk classification on your tool in the MCP Hub:

• read — public information.
• read_pii — returns personal data (GDPR Art. 4(1)). Platform floor for this classification is identified.
• write — state-changing. Platform floor is identified.
• destructive — irreversible or financially material. Platform floor is high-assurance.

A lookup tool is typically read_pii because it returns the caller’s personal information. The platform won’t call it under anonymous, which means the verification specialist can’t use it in flows where the caller hasn’t yet started a verification handshake — except via the platform’s internal bypass token (described in the next section).

The verification-agent bypass

To resolve the chicken-and-egg (“we need to verify the caller but the lookup tool requires identified”), the platform issues a short-lived signed token to the verification specialist that bypasses the assurance gate for the duration of the verification flow. Two important properties:

1. The bypass binds to the specific contact_id being verified. If your tool returns data for a different contact under the bypass, the platform rejects the response (mismatched principal binding).
2. The bypass is logged. Every bypass use writes a verification_agent_context_used identity_event with the tool name and the target contact id. Auditors can review these.

Your tool does not need to know whether it was called under the bypass — the lookup result is read the same way. The bypass is enforced at the platform side.

Testing your tool

Use the platform’s MCP Hub testing surface (in the dashboard, MCP Hub -> your connection -> Test) to invoke your tool with sample contact ids and inspect the response shape. The platform’s debug bench can simulate a verification specialist flow against your tool to confirm the LLM can form sensible questions from the response.