Designing an MCP Server for AI Assistant Discovery

Nine Read-Only Tools as a Contract

Nine tools cover the discovery job:

Specialist search mirrors the filter set the website already uses, so there are no new search semantics to maintain. Results are capped at 20 per page across three pages, inside a 25,000-token payload ceiling.

Every tool carries a human-readable title and the full annotation set: readOnlyHint, destructiveHint, idempotentHint. Both are contract-level requirements. In DBB's own connector submissions, a missing read-only annotation accounted for roughly 30% of first-submission rejections, and a missing human-readable title was the most common rejection cause at the Anthropic connectors directory.

The tool specifications live in a single shared package consumed by both the public protocol wire and the internal path, so the two surfaces cannot drift apart.

No Language Model Inside the Server

A decision record fixed the intelligence in the client. ChatGPT, Claude and client's own chatbot already decide when to invoke a tool and how to compose the answer.

A model inside the server would have added cost on every call, a vendor data-processing dependency, prompt-injection surface, and non-determinism. The service stays deterministic and cacheable, and sits outside every AI-vendor compliance conversation.

Data-Exposure Envelope Enforced in Code

The line between what reaches an AI answer and what stays on the platform lives in response mappers that only know envelope fields. Property-based tests assert that nothing outside the envelope can serialize, so a field absent from the mapper cannot leak.

Response schemas are versioned in the repository beside the tool specs, with a breaking-change check in continuous integration. The data-freshness field is sourced from the read model's own index timestamps.

Tenant Scoping Across Fourteen Markets

The platform runs fourteen tenants: nine country markets, four partner deployments and a default. The design proposes a single public endpoint at the apex, with tenant as a required, server-validated enum on every tool call.

Two questions were left for the proof of concept to answer with evidence: cross-region latency for AU-tenant queries served from the EU deployment, and whether assistants handle a tenant parameter gracefully in practice. Per-market endpoints remain available later by supersession, without breaking the apex contract.

Quotas and Extraction Economics

Rate and quota counters live in a distributed store, either managed Redis or a DynamoDB token bucket. Nothing rate-limiting lives in process memory, because a per-process counter multiplies the effective limit by the number of workers running.

Per-client quotas are sized against the page caps so that harvesting the corpus through the tools is slower than crawling the same content from the public sitemap. The Gate 1 cost model prices tool calls at expected volume and at the quota-capped abuse ceiling, alongside a statement of the marginal OpenSearch load, with a monthly budget alarm wired to a fail-closed breaker on the public path.

Nine Security Layers on the Public Path

Every external tool call passes nine checks in request order before any data leaves the platform:

No free text reaches a query builder unescaped. OpenSearch queries are constructed only through the existing repository query builders. Five abuse cases are enumerated for the security gate, each with its control and its test: IP-rotation extraction, quota probing, tenant-parameter fuzzing, oversized queries, and cache-busting of the GET manifest.

Latency, Caching and Error Behavior

The underlying queries already serve the website at production load, so the service adds mapping overhead only. The budget is p95 under 800ms warm and p99 under 2 seconds including cold start.

Cache headers are set per tool class:

The JSON-RPC error taxonomy is defined with its alerting: validation errors are client-side and raise no alert, tenant-not-enabled is client-side, upstream read-layer failures alert above 1% of calls in five minutes, and quota exhaustion returns a 429-equivalent tool error carrying retry-after. Errors return machine-readable codes and never leak stack traces or infrastructure names.

Distribution Through Official Directories

DBB tested the industry's working assumption that publishing a manifest at the well-known path is enough for an assistant to find a connector. No major AI client auto-discovers one.