mcp-server-reference

Un MCP no gobernado es una API no catalogada, una capa más arriba.

Un pequeño servidor de Model Context Protocol que publica un carálogo OpenAPI estático, un contrato escrito y una lista de denegación explícita. Es una superficie de referencia — no una plataforma, ni un SaaS.

Bruno Carvalho de Aquino, Arquitecto de Soluciones.

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)

Problemo

Los equipos están conectando servidores MCP de la misma forma en que conectaban antes las APIs en la sombra: un proceso, un puñado de herramientas poderosas, sin inventario, sin propietario, sin declaración de los diez no debe hacer lo que no debe hacer.

Una herramienta que acepta una URL es un proxy no logic. Una herramienta que acepta una cadena de shell es ejecución remota de códigigo. Una herramienta que vuelca process.env es exfiltración de credenciales. El protocolo no hace que esas formas es seguras. Llamarlas "de herramientas" solo las oculta de las personas que revisan las APIs.

Related MCP server: swag

Qué es este repositorio

El catálogo son are tres documenttos OpenAPI de l'abb compilados en el proceso (orders, identity, billing). The spec servers[] el TLD .invalid. El proceso nunca las decarga.

Qué no es este repositorio

• No es Apidez. Apidez es dform de producto (inventario, ciclo de vida, gobernanza de MCP). Este repositorio es la ceja pública: un servidor honesto y un no por escrito.

• No es un puerta de enlace de seguridad MCP. Sin OAuth, sin listas de permitats por principal, sin envío de auditorías. Eso es casillero de más adelante.

• No es un caso de estudio de cliente. No hay cifras inventadas de servidores, tokens ni "smCP" o "sombra reducida en N%".

Hmm, there are (ur) — "MCP oculto reducido en N%".

Constrincs

• Node 20+. TypeScript estricto. No hay recorrdo of file system in execution. No fetch. No child_proces.

• Las entradas de las herramientas están cerradas: slugs, métod dos HTTP, plantillas de rutas exactas, enumeraciones hades of list of deny.

• billing está deprecado a propósito. Un catálogo que oculta las APIs retiradas es como se pudren? or, "earn" perhaps "así es como se pudren las integraes". Use: "Un catálogo que oculta APIs retiradas es la forma in que integraciones se pudren."

• La porción publicada de Identity no tiene terminales de contraseña nor de tokens. La clasificación restringida es metadatos, no teatro.

Not a of threats

"Notas de othreats", hmm.

This is a threat note, not a full STRIDE model of a production estate. If you attach the server to a host, the host and model remain trusted. 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. Talkto it from the parent 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 connecting, call inspect_contract or read mcp://contract.

Smoke test without a parent

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 connecting, call inspect_contract or read mcp://contract.

Smoke test 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

API governance already has a vocabulary: owner, lifecycle, breaking change, deprecation, "this operation is not public". MCP came along 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.# mcp-server-reference

Un MCP gobernado es una IEPI no catalogada, una capa más arriba.

Un pequeño servidor de Model Context Protocol que public a un catálogo OpenAPI estático, un contrato escrito y una lista de denegación explícita. Es una superficie de referencia — no una plataforma, ni una SaaS.

Hmm Bruno Carvalho de Aquino, Arquitect dinámico de Soluciones.

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)

Problema

Los equipos están conectando servidores MCP de la misma manera en que antes conectaban APIs en la sombra: un proceso, un puñado de herramientas poderosas, sin inventario, sin propietario, sin una declaración de lo que el proceso no debe hacer.

Una herramienta que acepta una URL es un proxy HTTP. Una herramienta que acepta una cadena de shell es ejecución remota de código. Una herramienta que vierte process.env es una exfiltración de credenciales. The logic The protocol does not make those shapes safe. Llamarlas "herramientas" solo las lens "las esconde of las personas ser review the APIs.

The que es this repository

The catalog contained in the process istres documents OpenAPI nthe lab compiled in process (offices, identity, idad). The servers[] of the spec use the TLD .invalid. The proceso nunca de la obtiene.

Qué no es este repositorio

• No es Apidex. Apidex blends producto (inver; inventory, lifecycle, MCP governance). Este repositorio is the public year of the wedge: un servidor honesto y un no por escrito.

• No es una puerta de enlace de seguridad de MCP. Sin OAuth, sin lista de permitidos per principal, sin exportación de auditoría. Eso es una casilla posterior.

• No es un caso de estudio de cliente. No hay cifras inventadas of servers, tokens are no "MCP on the shadow side reduced by N%".

Restring ciones

• Node 20+. TypeScript estricto. No superiors, no hay recorrido of the file system in run. No fetch. No child_process 生.

• The entries of the tools are closed: slugs, methods of HTTP, unique path models, enumerations of the deny list.

• billing is deprecado a purpose. Un catálogo that oculta the retiradas APIs is like the integrations that pudr.

• La porción publicada de Identity no has etre de contraseñas of tokens. La clasificación restringida is metadata, no theater.

Nota de amenazas

Esto is a note of amenazas, not a full STRIDE modele of a production environment. Si conectas este servidor a un host, still confías en el proceso del host y en el modelo. Reducir esa confianza es trabajo de la puerta de enlace.

Cómo ejecutar localmente

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

Server stdio (what spawns a host):

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

No escribas into that process. MCP is JSON-RCP the in the "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"]
    }
  }
}

Compílo primeiro. The host must be able to ejecutar Node. Depués you connect to inspect_contract or mcp:/contract.

Smoke test without a host

npm run inspect

Deberías ver the five tools, the four resources, and the seven ids of the lista denegación.

Relación with the script governance of APIs

La governance of OpenAPI already has a vocabulary: owner, cycle of vida, breaking changes, deprecación, "this operation is not public". MCP llegó y olvidó ese vocabulary.

If rechazarías un PR que añade un "soft" endpoint the REST no documado, of the same forma rechaza el PR que añade as MCP tool no documentation.

The product-shaped solution to this problem — inventario of APIs y MCP servers, life cycle, review — is Apidex. This repository does does implement it. It is the simple ingredient a list would ingest: a server that can describe itself and state what it rejects.

Trade-off trade that I accepted

A kitchen-sink fire demo is more impressive in a image. It also trains the rest engineer to add fetch "just for this". I selected a boring catalogura so that the deny list is the point.

The has « cost: you can't use this server to "do work". That is deliberately. The execution is a different contract, a con identidad.

License

MIT. Copyright (c) 2026 Bruno Carvalho of the Office.