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.

What this repository is

Piece	Role
TypeScript MCP server (@modelcontextprotocol/server v2)	stdio process a host can spawn
Five tools	list / lookup / describe. No execution.
Four resources	contract, deny-list, catalog index, per-API spec
CONTRACT.md	Human manifest of the surface
DENY.md	Closed list of capabilities that will not be added
ADR-0001	Why the deny-list is part of the interface

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

Risk	How it shows up in MCP	Control here
SSRF	fetch(userUrl) or "load this swagger"	No URL arguments. Specs are imported.
RCE	run_command, bash -c	Not implemented. explain_deny("raw_shell").
Secret exfil	debug_env, home-directory read_file	No env or path tools. No secrets in the repo.
Prompt injection via specs	Remote OpenAPI that contains instructions	Catalog is reviewed git content.
Confused deputy	Host user grants the server; model picks the tool	Small surface. Contract is listable.
Shadow execution	Lookup tool that quietly calls the live API	get_operation returns invoked: false.

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.

API practice	MCP equivalent in this repo
Published OpenAPI	CONTRACT.md + inspect_contract
Path allowlist	Catalog ids + exact operation match
"Do not expose /admin"	DENY.md
Deprecated API still listed	billing lifecycle = deprecated
Contract test in CI	npm test + npm run typecheck

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.