mcp-server-reference
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-server-reference List all available catalog operations."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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: omada-controller-mcp
What this repository is
Piece | Role |
TypeScript MCP server ( | stdio process a host can spawn |
Five tools | list / lookup / describe. No execution. |
Four resources | contract, deny-list, catalog index, per-API spec |
Human manifest of the surface | |
Closed list of capabilities that will not be added | |
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. Nochild_process.Tool inputs are closed: slugs, HTTP methods, exact path templates, deny-list enums.
billingis 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 |
| No URL arguments. Specs are imported. |
RCE |
| Not implemented. |
Secret exfil |
| 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 |
|
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 buildstdio server (what a host spawns):
npm start
# or, without a prior build:
npm run devDo 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 inspectYou 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 |
|
Path allowlist | Catalog ids + exact operation match |
"Do not expose /admin" | |
Deprecated API still listed |
|
Contract test in CI |
|
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.
Available Tools
5 toolsexplain_denyExplain a denied capabilityA
Explain why a named capability is refused. Use this instead of asking the server to grow a shell, HTTP client, or secret reader.
Inputs: capability (required).
get_operationGet cataloged operationA
Return one operation from a cataloged API. Method and path must match the published spec exactly. This describes the operation; it does not invoke it.
Inputs: path (required), apiId (required), method (required).
inspect_contractInspect published contractA
Return the tool manifest, resource manifest, deny-list ids, and a statement of what this server is not.
Inputs: no named parameters.
list_catalogList API catalogA
List the static OpenAPI catalog entries published with this server. Returns id, owner, lifecycle, classification, and operation count. No network.
Inputs: no named parameters.
lookup_apiLookup cataloged APIA
Return one imported OpenAPI document by catalog id (orders, identity, billing). Rejects unknown ids. Does not fetch URLs from the spec.
Inputs: apiId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a completely distinct purpose: listing catalogs, fetching a specific API document, retrieving a single operation, inspecting the server contract, and explaining deny behavior. No overlap or ambiguity exists.
All tool names follow a consistent lowercase verb_noun pattern (list_catalog, lookup_api, get_operation, inspect_contract, explain_deny), making the surface predictable and easy to navigate.
Five tools is precisely scoped for a read-only reference server. Each tool fills a necessary role without redundancy, and the count is neither too sparse nor overloaded for the stated purpose.
The tool set covers the full lifecycle for exploring static OpenAPI catalogs: listing, retrieving documents, drilling into operations, inspecting the server contract, and understanding denied capabilities. No apparent dead ends or missing operations for its domain.
Related MCP Connectors
Guarded MCP server for agent-readable business truth, provenance, readiness, and discovery.
Read-only discovery of ChatGXT's integration catalog and public MCP capabilities.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Discover and inspect public Runx skills before installing them. This read-only hosted MCP exposes search_skills and get_skill. The Apache-2.0 Rust runtime executes skills locally with scoped authority, approval gates and signed receipts. Docs: https://runx.ai/docs/mcp.
Related MCP Servers
- AlicenseAqualityDmaintenanceA read-only MCP server for navigating OpenAPI / Swagger specifications, enabling agents to search endpoints, retrieve parameters and schemas, and inspect authentication without loading the full spec into context.997 npmMIT
- AlicenseAqualityBmaintenanceEnables MCP-aware agents to query and manage a TP-Link Omada SDN controller by searching, inspecting, and calling operations from its live OpenAPI catalog.71MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to resolve, inspect, acquire, verify, and query routes, capabilities, schema, and health for public and authorized web resources, with fail-closed statuses and artifact production.MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to browse a read-only catalog of published products and their documented interfaces, listing entries, fetching one by stable ID, and searching names, descriptions, and limitations with optional protocol filters. It also exposes the versioned manifest as a resource and a prompt that helps clients match a task to catalog entries without inventing unsupported capabilities.MIT