Lockspec MCP server

LockSpec

Your AI coding agent writes code that calls your API, but it guesses parts of the contract that it can't see and doesn't know about. It invents field names, calls paths that don't exist, and gets the types wrong. LockSpec is an MCP server that gives the agent the real contract from your OpenAPI spec. When the agent needs an endpoint signature or a type, it gets the exact shape your API accepts.

Most API context tools for agents cover public libraries. LockSpec is for any API that you have a spec for, regardless of whether it's private, internal, or a third party's.

v1 supports OpenAPI 3.0 and 3.1.

Why

You might ask why the agent can't just read the spec from your repo. This works fine in many cases. But if you're working with a spec that the agent can't access (because it's not in the repo, or because it's too large to fit into context), the agent can't get accurate information about the contract it needs to fulfill. You might also want the agent pinned to a specific spec version you choose, not whatever is currently the latest version in the repo. LockSpec loads the spec you provide, indexes it, and serves answers from a pinned snapshot that you control. It returns only the slice that the agent asked for, so an agent can ground the code it writes in the actual contract rather than hallucinating it.

LockSpec can also help agents prevent API version skew. Suppose prod runs v1, a few services already moved to v2, and both are live. You want the agent to write against the right one the first time around. Writing against the wrong one breaks tests, or worse, ships a broken call. With LockSpec, you can load multiple versions of the same API spec at once. You control which one the agent uses. When more than one version of a spec is loaded, the tools that feed code-writing stop before writing code to ask which version should be used. The agent commits to a version on purpose instead of using the one that it saw most recently.

When the agent has a draft request, validate_call checks it against the pinned spec and reports any structural problems it finds. It's a check that catches structural mistakes in the draft before they fail tests and burn extra turns.

Install

Requires Node 22 or newer. Your MCP client runs it through npx:

npx lockspec

From source

git clone https://github.com/LockSpec/lockspec.git
cd lockspec
npm install
npm run build      # compiles TypeScript to dist/
node dist/index.js # starts the server over stdio

Connect your agent

LockSpec runs locally over stdio. Point your MCP client at the lockspec command:

{
  "mcpServers": {
    "lockspec": { "command": "npx", "args": ["lockspec"] }
  }
}

• Claude Code: claude mcp add lockspec -- npx lockspec
• Gemini CLI: gemini mcp add lockspec npx lockspec
• Codex: codex mcp add lockspec -- npx lockspec
• Cursor: add the block above to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global).
• Cline / Windsurf: add the block above to the client's MCP settings (clinemcpsettings.json for Cline).

To run from a source checkout instead of npm, point command/args at the built entrypoint:

{
  "mcpServers": {
    "lockspec": { "command": "node", "args": ["/absolute/path/to/lockspec/dist/index.js"] }
  }
}

The tools

Shortened. The full README is on GitHub.