The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Lockspec listing page.
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.
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.
Requires Node 22 or newer. Your MCP client runs it through npx:
LockSpec runs locally over stdio. Point your MCP client at the lockspec command:
claude mcp add lockspec -- npx lockspecgemini mcp add lockspec npx lockspeccodex mcp add lockspec -- npx lockspec.cursor/mcp.json (project) or ~/.cursor/mcp.json (global).cline_mcp_settings.json for Cline).To run from a source checkout instead of npm, point command/args at the built entrypoint:
| Tool | What it does |
|---|---|
load_spec | Ingest an OpenAPI file, URL, or text; normalize, index, and pin a version. |
find_endpoint | Find operations by intent or by exact path/operationId. |
find_type | Find named schemas and types. |
get_signature | Exact request and response shape: params, required fields, types. |
validate_call | Structurally validate a draft request against the spec and report what's wrong. |
list_specs | What's loaded, and which version is active. |
activate_version | Switch the active (pinned) version. |
remove_spec | Remove a spec or a single version. |
diff_versions | Structural diff of two versions, classified breaking or non-breaking. |
load_spec fetches a spec once, normalizes it (bundles external $refs, reconciles 3.0 and 3.1), hashes the result to use as the version's identity, and stores it under ~/.lockspec/. After that everything is pinned and offline. Your specs never leave your machine.
Multiple specs, and multiple versions of one spec, coexist and are queried independently. Each spec has one active version, used when you don't name one. When more than one version is loaded, get_signature and validate_call won't guess. They return an error asking you to pin a version. find_endpoint and find_type use the active version and tell you which one they used.
find_endpoint scores and ranks operations by intent, returning the match or matches the agent will work with.
get_signature returns the exact request body schema: required fields, types, and allowed values.
A structurally valid draft body returns valid: true with no errors.
validate_call collects all structural violations in one pass. Missing required fields, type mismatches, enum failures:
When two versions of the same spec are loaded, get_signature and validate_call refuse to guess which one you mean: