Server data from the Official MCP Registry
MCP server giving AI coding agents version-pinned API context from your OpenAPI specs.
MCP server giving AI coding agents version-pinned API context from your OpenAPI specs.
Valid MCP server (1 strong, 1 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.
3 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-lockspec-lockspec": {
"args": [
"-y",
"lockspec"
],
"command": "npx"
}
}
}From the project's GitHub README.
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:
npx lockspec
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
LockSpec runs locally over stdio. Point your MCP client at the lockspec command:
{
"mcpServers": {
"lockspec": { "command": "npx", "args": ["lockspec"] }
}
}
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:
{
"mcpServers": {
"lockspec": { "command": "node", "args": ["/absolute/path/to/lockspec/dist/index.js"] }
}
}
| 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.
find_endpoint({ query: "create" })
{
"ok": true,
"spec_id": "petstore",
"version_id": "sv_f403f8b0c4465bd7db52a4cd",
"results": [
{
"operation_key": "POST:/pets",
"operation_id": "createPet",
"summary": "Create a pet"
}
],
"truncated": false
}
get_signature returns the exact request body schema: required fields, types, and allowed values.
get_signature({ operation_id: "createPet" })
{
"ok": true,
"spec_id": "petstore",
"version_id": "sv_f403f8b0c4465bd7db52a4cd",
"operation_key": "POST:/pets",
"method": "POST",
"path": "/pets",
"operation_id": "createPet",
"summary": "Create a pet",
"deprecated": false,
"parameters": [],
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": "…"
}
}
}
},
"truncated_paths": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["id", "name"],
"examples": [
{
"id": 1,
"name": "Rex",
"status": "available"
}
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"tag": {
"type": ["string", "null"]
},
"weight": {
"type": "number",
"exclusiveMinimum": 0
},
"status": {
"type": "string",
"enum": ["available", "pending", "sold"]
}
}
}
}
}
}
}
A structurally valid draft body returns valid: true with no errors.
validate_call({ operation_id: "createPet", request: { body: { id: 1, name: "Rex" } } })
{
"ok": true,
"valid": true,
"spec_id": "petstore",
"version_id": "sv_f403f8b0c4465bd7db52a4cd",
"operation_key": "POST:/pets",
"errors": [],
"warnings": []
}
validate_call collects all structural violations in one pass. Missing required fields, type mismatches, enum failures:
validate_call({ operation_id: "createPet", request: { body: { id: "1", status: "unknown" } } })
{
"ok": true,
"valid": false,
"spec_id": "petstore",
"version_id": "sv_f403f8b0c4465bd7db52a4cd",
"operation_key": "POST:/pets",
"errors": [
{
"location": "body",
"pointer": "/id",
"code": "type",
"message": "Expected integer, got string.",
"expected": "integer",
"actual": "string"
},
{
"location": "body",
"pointer": "/name",
"code": "required",
"message": "Missing required property 'name'."
},
{
"location": "body",
"pointer": "/status",
"code": "enum",
"message": "Value is not one of the allowed values [available, pending, sold].",
"expected": ["available", "pending", "sold"],
"actual": "unknown"
}
],
"warnings": []
}
When two versions of the same spec are loaded, get_signature and validate_call refuse to guess which one you mean:
get_signature({ operation_id: "createInvoice" })
{
"ok": false,
"error": {
"code": "ambiguous",
"message": "Spec \"billing-api\" has 2 loaded versions (1.0.0, 2.0.0) — pass version (version_id or version_label) to choose one.",
"details": {
"loaded_versions": [
{
"version_id": "sv_a5a2fdfa11e7038e6eb6b4b1",
"version_label": "1.0.0",
"active": false
},
{
"version_id": "sv_bcfbfdc5783f3292208c9dc7",
"version_label": "2.0.0",
"active": true
}
]
}
}
}
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Web content fetching and conversion for efficient LLM usage
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.