How do you build an MCP server in Node.js for up to date API docs?

To keep an AI assistant current on your API, build a small Model Context Protocol server in Node.js that exposes tools which fetch the live OpenAPI spec or docs pages on request. The assistant then reads today's reference instead of whatever was in its training data. Add allow lists and size limits so fetched text cannot misuse the session.

Why do assistants get API details wrong?

A model's training data has a cutoff. An endpoint renamed last month, a parameter deprecated last week or a new version header will be missing or wrong in its memory. The model often answers anyway, with confident but outdated code.

MCP gives the assistant a standard way to call your code. The MCP documentation describes three kinds of server capability: resources (file like data such as API responses), tools (functions the model can call, with user approval) and prompts (pre written templates). For current docs, tools and resources are the useful pair.

What should the server expose?

Keep the surface small. Three tools are enough for most teams.

• search_docs takes a query and returns titles and URLs from your docs index.
• get_endpoint takes a path and method and returns the matching entry from your OpenAPI file, including parameters and response shapes.
• get_changelog returns recent changes, so the assistant can tell when something is new.

A resource that serves the full spec by version is also handy for clients that prefer to browse.

How do you set it up in Node.js?

The official TypeScript SDK lives in the MCP typescript-sdk repository. The outline looks like this.

1. Create a project and install the SDK and a schema library such as zod with npm.
2. Create a server object with a name and version.
3. Register each tool with a description, an input schema and a handler that returns text content.
4. In the handler, fetch your spec from a fixed URL, cache it for a short time and extract only the part asked for.
5. Connect the server to a transport. A local STDIO transport suits a developer's own machine. An HTTP transport suits a shared team server.
6. Test with the MCP Inspector before you connect a real assistant.

Treat the tool descriptions as part of your product. Models choose tools by reading them, so say plainly what each tool returns and when to use it.

What breaks first?

Logging on STDIO. The MCP build guide warns that a STDIO server must never write to stdout, because that corrupts the JSON-RPC messages. Its example is Python, but the rule is about the protocol. In Node.js, send diagnostics to stderr, for example with console.error, and avoid console.log entirely.

Stale caches. If you cache the spec for a day you have rebuilt the original problem. Use a short time to live or an ETag check, and return the spec's version and fetch time in every answer so the assistant can state how fresh it is.

Huge responses. A full OpenAPI file can be megabytes. Return the slice requested, with a size cap.

How do you keep it safe?

Fetched documentation is data, but a model may treat text as instructions. If your docs include user contributed pages, a hostile page could carry text aimed at the assistant. The MCP specification publishes security best practices worth reading before you expose a server beyond your own machine. In addition:

• Fetch only from an allow list of your own hosts. Never let a tool take an arbitrary URL.
• Keep tools read only. A docs server has no reason to write anything.
• Authenticate remote servers and log each call.
• Strip or flag content that looks like instructions to the assistant.

Constructed example: your payments API moves from v2 to v3 on a Monday. With a live get_endpoint tool, a developer's assistant reads the v3 entry that morning and warns that the old amount field is gone. Without it, the assistant keeps generating v2 calls for months.

Quick check

Safeguard runs its own MCP server at mcp.safeguard.sh with unlimited tool calls on every plan, which is a useful reference for how a hosted, authenticated server is offered.

Sources

• Model Context Protocol, Build an MCP server
• Model Context Protocol, security best practices
• MCP TypeScript SDK repository
• MCP Inspector

Last reviewed: 18 October 2026.