@octri/mcp

An MCP server that turns your API documentation into tools an AI assistant can call. Claude, Cursor, VS Code Copilot, and any other MCP client can search your endpoints, open a guide, pull a ready-to-use SDK snippet in any supported language, and check the changelog for breaking changes, all from the same OpenAPI spec your docs are built from.

Octri turns an OpenAPI spec into a documentation site, client SDKs for ten languages, an MCP server your AI assistant can call, and monitoring for the API behind them. This package is the MCP server. See octri.dev/mcp.

Node 20 or newer. Runs over stdio for a local client, or Streamable HTTP when you host it.

Install

npx -y @octri/mcp

Most clients are configured with that command, so a global install is optional. The Installation section below has the exact config block for each one.

Or install it in one click. VS Code asks for your project ID; Cursor writes YOUR_PROJECT_ID into its mcp.json for you to replace.

Listed in the official MCP Registry as dev.octri/mcp.

Tools

Installation

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "my-api-docs": {
      "command": "npx",
      "args": ["@octri/mcp", "--project-id", "YOUR_PROJECT_ID"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "my-api-docs": {
      "command": "npx",
      "args": ["@octri/mcp"],
      "env": {
        "OCTRI_PROJECT_ID": "YOUR_PROJECT_ID"
      }
    }
  }
}

VS Code (Copilot / MCP extension)

Add to .vscode/mcp.json:

{
  "servers": {
    "my-api-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["@octri/mcp", "--project-id", "YOUR_PROJECT_ID"]
    }
  }
}

Environment variables

* Required unless every tool call passes projectId explicitly.

Credentials for the API being called

Operation tools call your real API, and these supply its credentials:

All of these are sent as HTTP headers. An API that takes its credentials in the request body instead (Plaid's client_id and secret, for example) is not served by them: those are ordinary body fields, so they appear as tool arguments and the agent passes them like any other field. Setting OCTRI_API_KEY for such an API adds a header it ignores.

Remote hosting

Use Streamable HTTP (MCP_TRANSPORT=http), the transport the MCP spec has defined for remote servers since revision 2025-03-26 and the one a current client tries first:

docker build -t octri-mcp .

docker run -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e OCTRI_PROJECT_ID=YOUR_PROJECT_ID \
  octri-mcp

It serves a single endpoint, POST /mcp, and runs statelessly, so requests carry no session and any number of replicas can sit behind a load balancer. Point a remote MCP client at http://your-host:3000/mcp.

Legacy HTTP+SSE transport

MCP_TRANSPORT=sse serves the older 2024-11-05 design, kept so existing deployments keep working. It exposes GET /sse to open a connection and POST /messages?sessionId=<id> to relay client messages. Prefer http for anything new.

Binding and origins

Both HTTP transports bind 127.0.0.1 by default and refuse any request whose Origin is not listed in MCP_ALLOWED_ORIGINS, or whose Host is not loopback. This server holds your API credentials, and any page the browser visits can reach a loopback port. Widen MCP_HOST only behind a proxy you control, and list origins explicitly.

Local development

# Build
pnpm build

# Run in stdio mode
OCTRI_PROJECT_ID=my-project node dist/index.js

# Run in Streamable HTTP mode (POST /mcp)
MCP_TRANSPORT=http OCTRI_PROJECT_ID=my-project node dist/index.js

# Run in the legacy SSE mode
MCP_TRANSPORT=sse OCTRI_PROJECT_ID=my-project node dist/index.js

Publishing

pnpm build
npm publish --access public

Requires an npm account with access to the @octri scope.

The rest of Octri

Monitoring runtimes

Node · Python · Go · Ruby · Rust · PHP · Java · Kotlin · Swift · Dart

Documentation · Pricing · Changelog

MIT licensed.