Work / mcp-surface

Platform2026

An MCP surface that refuses to boot if a tool lies about itself

83 tools, five live resources over server-sent events, OAuth with dynamic client registration for third-party clients, and a registry validated at start-up.

TypeScriptFastifyModel Context ProtocolSSEOAuth 2.0PostgreSQLDrizzleZod

The problem

The product’s agents needed a stable, discoverable surface of tools and resources shared by four clients (parent app, child app, web, admin), and third-party MCP clients needed to authenticate against it safely. A tool catalog that drifts from its own descriptions is worse than none: an agent trusts the annotation, not the code.

What I built

Transport and resources. An SSE transport with a subscription registry, and a change-detection event bus that turns database changes into resource updates. Five live resources on top of it, covering the family’s day, the child’s rewards, screen-time requests and family activity, so an agent sees state change without polling.

The catalog. Every tool carries annotations: what it reads, what it mutates, whether it is idempotent, a human-readable title. A boot-time validator checks the whole registry against the schema and against the actual handlers, and the service does not start if any tool’s declaration disagrees with what it does. That single gate removed a class of incidents in which an agent called a tool it believed to be read-only.

Auth for outside clients. OAuth 2.0 for MCP clients, with dynamic client registration hardened by a redirect-URI allow gate and a rate limit on the facade, a native-redirect shim for clients on private-use schemes, and a domain-verification route for a large vendor’s app platform. The scopes moved into their own package so the parent app, the MCP service and the admin tools agree on them by construction.

The design stance

An MCP server is a contract with a non-human reader. Everything that a human reviewer would catch by reading the docs has to be enforced by the server, because the agent will not read the docs. Validation at boot, typed schemas end to end, and annotations that are tested, not written.