mcp-server-reference

Ungoverned MCP is an uncatalogued API, one layer up.

A small Model Context Protocol server that publishes a static OpenAPI catalog, a written contract, and an explicit deny-list. It is a reference surface — not a platform and not a SaaS.

Bruno Carvalho de Aquino, Solutions Architect.

MCP host (Cursor, Claude, …)
        |
        | stdio
        v
+---------------------------+
|  mcp-server-reference     |
|                           |
|  tools  = catalog lookup  |
|  resources = contract     |
|  deny-list = interface    |
+---------------------------+
        |
        | imported modules only
        v
   orders | identity | billing
   (OpenAPI snippets, no fetch)

Problem

Teams are wiring MCP servers the way they once wired shadow APIs: a process, a few powerful tools, no inventory, no owner, no statement of what the process must not do.

A tool that accepts a URL is an HTTP proxy. A tool that accepts a shell string is remote code execution. A tool that dumps process.env is credential exfiltration. The protocol does not make those shapes safe. Naming them "tools" just hides them from the people who review APIs.

Related MCP server: swag

What this repository is

The catalog is three lab OpenAPI documents compiled into the process (orders, identity, billing). Spec servers[] use the .invalid TLD. The process never fetches them.

What this repository is not

• Not Apidex. Apidex is the product-shaped answer (inventory, lifecycle, MCP governance). This repo is the public wedge: one honest server and a written no.

• Not an MCP security gateway. No OAuth, no per-principal allowlist, no audit shipping. That is a later box.

• Not a customer case study. No invented counts of servers, tokens, or "shadow MCP reduced by N%".

Constraints

• Node 20+. TypeScript strict. No runtime filesystem walk. No fetch. No child_process.

• Tool inputs are closed: slugs, HTTP methods, exact path templates, deny-list enums.

• billing is deprecated on purpose. A catalog that hides sunset APIs is how integrations rot.

• Identity's published slice has no password or token endpoints. Restricted classification is metadata, not theatre.

Threat notes

This is a threat note, not a full STRIDE model of a production estate. If you attach this server to a host, you still trust the host process and the model. Reducing that trust is gateway work.

How to run locally

npm install
npm test
npm run typecheck
npm run inspect    # prints the contract JSON
npm run build

stdio server (what a host spawns):

npm start
# or, without a prior build:
npm run dev

Do not type into that process. MCP is JSON-RPC on stdin/stdout. Talk to it from a host.

Cursor / Claude Desktop

{
  "mcpServers": {
    "catalog": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-reference/dist/index.js"]
    }
  }
}

Build first. The host must be able to spawn Node. After connect, call inspect_contract or read mcp://contract.

Smoke without a host

npm run inspect

You should see the five tools, the four resources, and the seven deny-list ids.

Relation to API governance

OpenAPI governance already has a vocabulary: owner, lifecycle, breaking change, deprecation, "this operation is not public". MCP arrived and forgot that vocabulary.

If you would fail a PR that adds an undocumented REST endpoint, fail the PR that adds an undocumented MCP tool.

The product-shaped version of this problem — inventory of APIs and MCP servers, lifecycle, review — is Apidex. This repository does not implement that. It shows the primitive a catalog would ingest: a server that can describe itself and state what it refuses.

Trade-off I accepted

A kitchen-sink demo is more impressive in a screenshot. It also trains the next engineer to add fetch "just for this". I chose a boring catalog so the deny-list is the point.

The cost: you cannot use this server to "do work". That is intentional. Execution is a different contract, with identity.

License

MIT. Copyright (c) 2026 Bruno Carvalho de Aquino.