scalar-mcp

MCP server that indexes a Scalar/OpenAPI document and returns rich endpoint context.

It can discover the OpenAPI JSON URL from a Scalar docs page, or read a direct OpenAPI JSON URL/file.

Usage

Pass one source when starting the MCP server:

scalar-mcp --docs-url http://172.30.10.16:8080/docs

or:

scalar-mcp --openapi-url http://172.30.10.16:8080/openapi.json
scalar-mcp --openapi-file /path/to/openapi.json

Environment variables are also supported:

SCALAR_DOCS_URL=http://172.30.10.16:8080/docs scalar-mcp
OPENAPI_URL=http://172.30.10.16:8080/openapi.json scalar-mcp
OPENAPI_FILE=/path/to/openapi.json scalar-mcp

The server refreshes every 30 minutes by default:

scalar-mcp --docs-url http://172.30.10.16:8080/docs --poll-interval-ms 1800000

blob: URLs are not supported. Browser blob URLs only exist inside the browser session that created them, so an MCP server cannot poll them. Use the Scalar docs URL, the discovered OpenAPI JSON URL, or an exported local JSON file.

MCP Tools

• refresh_openapi_index - manually refresh the cached OpenAPI document. Passing source makes that source the active polling source.
• list_endpoints - list indexed endpoints with optional filters.
• get_endpoint_context - return full endpoint context including parameters, request payloads, response payloads, security, servers, tags, examples, and resolved schemas.

Codex Config

Add this to ~/.codex/config.toml after publishing to npm:

[mcp_servers.scalar]
command = "npx"
args = ["-y", "scalar-mcp", "--docs-url", "http://172.30.10.16:8080/docs"]

For local development before publishing:

[mcp_servers.scalar]
command = "node"
args = ["/Users/elhamdev/work/scalar-mcp/dist/index.js", "--docs-url", "http://172.30.10.16:8080/docs"]

Claude Code Config

After publishing to npm:

claude mcp add scalar -- npx -y scalar-mcp --docs-url http://172.30.10.16:8080/docs

For local development before publishing:

claude mcp add scalar -- node /Users/elhamdev/work/scalar-mcp/dist/index.js --docs-url http://172.30.10.16:8080/docs

Development

npm install
npm run typecheck
npm run build
npm start -- --docs-url http://172.30.10.16:8080/docs

Publish

The package name scalar-mcp is available on npm as of June 9, 2026.

npm login
npm publish

The prepack script builds dist/ before packing or publishing.