Take a snapshot of an MCP server’s contract
const url = 'https://beta-api.plune.ai/v1/mcp-servers/example/snapshots';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"server":{"name":"shop-mcp","version":"1.4.0"},"environment":"beta","capabilities":{"tools":{"listChanged":false}},"tools":[{"name":"get_order","description":"Read one order by its id.","inputSchema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]},"annotations":{"readOnlyHint":true}},{"name":"list_orders","description":"List the latest orders.","inputSchema":{"type":"object","properties":{"limit":{"type":"integer"}}}}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://beta-api.plune.ai/v1/mcp-servers/example/snapshots \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "server": { "name": "shop-mcp", "version": "1.4.0" }, "environment": "beta", "capabilities": { "tools": { "listChanged": false } }, "tools": [ { "name": "get_order", "description": "Read one order by its id.", "inputSchema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "annotations": { "readOnlyHint": true } }, { "name": "list_orders", "description": "List the latest orders.", "inputSchema": { "type": "object", "properties": { "limit": { "type": "integer" } } } } ] }'A person, or a write token without X-Plune-Session (CI, which is how plune mcp snapshot sends a contract). An agent is refused (403 agent_proposes). The snapshot holds what the server itself answered. Refused (400): a field the snapshot does not name, at the top and inside each entry; and a key that carries a credential or a connection (authorization, headers, env, command, args, cookie, token, password, secret, apikey, … in any letter case, and any key ending in token, secret, password or apikey) at any depth of capabilities and of a tool’s annotations and execution - the answer names the path, never the value. NOT checked: the text the server wrote (description, instructions, title) and the schemas (inputSchema, outputSchema, with their defaults and examples) are kept as sent, so a secret a server writes there is stored. The hash is taken from the canonical JSON of the contract, not from the text sent. The same contract as the latest snapshot’s adds none: the latest comes back with status 200 and the same body as the first time (201), and the tools are marked seen again. Any other contract is the next number, and the changes against the snapshot before it are stored. A server holds at most 200 snapshots (429, quota.kind mcpSnapshotsPerServer). A name listed twice in a list is 400. Logged as an update of the project: the hash and the count, never the contract.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The server’s id
Request Body required
Section titled “Request Body required ”What a server answered: its name and version, capabilities, instructions, and the entries of tools/list, resources/list, resources/templates/list and prompts/list - the shape plune mcp snapshot writes, so a file can be sent as it is. Every object that names its fields is closed: a field it does not name is refused (400), not dropped; and a key that carries a credential (headers, env, command, token, password, …) is refused at any depth of capabilities, and of a tool’s annotations and execution. The text a server wrote and the schemas are kept as sent. A list left out or null is a list the server does not declare; [] is a list it declares and holds nothing in.
object
What the CLI’s file calls itself; not stored
The CLI file’s version; not stored
The connection of the CLI’s file; not stored - the server’s transport is the server’s
Where the server was running. Not part of the contract and not of its hash
object
As the server declared them
object
A name is listed once
object
object
object
object
object
Contract fields of Plune’s own server: visibility (core or discoverable) and write
object
Entries of resources/list: uri, and name, title, description, mimeType
object
Entries of resources/templates/list: uriTemplate, and name, title, description, mimeType
object
Entries of prompts/list: name, and title, description, arguments
object
Examples
The first contract of a server
{ "server": { "name": "shop-mcp", "version": "1.4.0" }, "environment": "beta", "capabilities": { "tools": { "listChanged": false } }, "tools": [ { "name": "get_order", "description": "Read one order by its id.", "inputSchema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "annotations": { "readOnlyHint": true } }, { "name": "list_orders", "description": "List the latest orders.", "inputSchema": { "type": "object", "properties": { "limit": { "type": "integer" } } } } ]}A later one: a required parameter and a new tool
{ "server": { "name": "shop-mcp", "version": "1.4.0" }, "environment": "beta", "capabilities": { "tools": { "listChanged": false } }, "tools": [ { "name": "get_order", "description": "Read one order by its id.", "inputSchema": { "type": "object", "properties": { "id": { "type": "string" }, "region": { "type": "string" } }, "required": [ "id", "region" ] }, "annotations": { "readOnlyHint": true } }, { "name": "refund_order", "description": "Refund one order.", "inputSchema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } ]}Responses
Section titled “ Responses ”The same contract as the latest snapshot’s: that snapshot, unchanged
A snapshot of a server’s contract. Never changed after it is written.
object
Counts from 1 within the server
SHA-256 of the canonical JSON of the contract (keys sorted at every level): the same contract has the same hash
Where the server was running when it answered. Not part of the contract and not of its hash
Tools listed; null when the server declares no tool list. 0 is a list that holds nothing
The contract as stored: every section present, null where the server declares none; the entities of each list in the order of their key
object
object
object
object
object
object
object
Example
{ "id": "6f1c2b3a-0000-4000-8000-000000002460", "projectId": "u-shop::default", "serverId": "6f1c2b3a-0000-4000-8000-000000002458", "number": 1, "hash": "b7e2c4a19d3f58601a4c9e7d2b5f8031c6a9d4e7f1b2035a8c6d9e0f3a41b72c", "environment": "beta", "tools": 2, "createdBy": "6f1c2b3a-0000-4000-8000-0000000000a2", "createdAt": "2026-11-13T09:00:00.000Z", "content": { "server": { "name": "shop-mcp", "version": "1.4.0" }, "instructions": null, "capabilities": { "tools": { "listChanged": false } }, "tools": [ { "name": "get_order", "description": "Read one order by its id.", "inputSchema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "annotations": { "readOnlyHint": true } }, { "name": "list_orders", "description": "List the latest orders.", "inputSchema": { "type": "object", "properties": { "limit": { "type": "integer" } } } } ], "resources": null, "resourceTemplates": null, "prompts": null }}A new snapshot
A snapshot of a server’s contract. Never changed after it is written.
object
Counts from 1 within the server
SHA-256 of the canonical JSON of the contract (keys sorted at every level): the same contract has the same hash
Where the server was running when it answered. Not part of the contract and not of its hash
Tools listed; null when the server declares no tool list. 0 is a list that holds nothing
The contract as stored: every section present, null where the server declares none; the entities of each list in the order of their key
object
object
object
object
object
object
object
Example
{ "id": "6f1c2b3a-0000-4000-8000-000000002460", "projectId": "u-shop::default", "serverId": "6f1c2b3a-0000-4000-8000-000000002458", "number": 1, "hash": "b7e2c4a19d3f58601a4c9e7d2b5f8031c6a9d4e7f1b2035a8c6d9e0f3a41b72c", "environment": "beta", "tools": 2, "createdBy": "6f1c2b3a-0000-4000-8000-0000000000a2", "createdAt": "2026-11-13T09:00:00.000Z", "content": { "server": { "name": "shop-mcp", "version": "1.4.0" }, "instructions": null, "capabilities": { "tools": { "listChanged": false } }, "tools": [ { "name": "get_order", "description": "Read one order by its id.", "inputSchema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "annotations": { "readOnlyHint": true } }, { "name": "list_orders", "description": "List the latest orders.", "inputSchema": { "type": "object", "properties": { "limit": { "type": "integer" } } } } ], "resources": null, "resourceTemplates": null, "prompts": null }}Invalid JSON or body, a field the snapshot does not name, or a name listed twice
object
Example generated
{ "error": "example"}No / invalid token or session
A reader, a read token, or an agent (agent_proposes: the catalog is not written by an agent yet)
object
Example generated
{ "error": "example"}No such MCP server in your project
object
Example generated
{ "error": "example"}Two refusals share this status, and what to do about them is opposite. Rate-limited — the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442, #2092): Retry-After carries the seconds until the window rolls over, and waiting that long is the way out. Quota reached — a ceiling on what the project holds (runs in the last 24 hours, test cases, items waiting in the review queue, rules in force in the project’s memory): { error, quota }. A retry straight away frees nothing, so do not loop on it; the message says what makes room — deleting cases, working the queue down, an operator raising the limit — and the run quota, a rolling 24 hours, frees its oldest runs as they age out. Tell the two apart by the body: a 429 whose body has a quota object is a quota, one without it is a throttle. quota carries kind, limit, used, remaining and resetsAt: the figures behind the sentence, and for the run quota the instant its oldest run ages out (#1258). Retry-After is sent on a quota only where there is such an instant (the run quota: the whole seconds, at least 1, until resetsAt); the case, review-queue and project quotas free only by an action, have resetsAt: null, and send no Retry-After. GET /v1/quotas reads the same figures without a refusal.
object
The body of a 429 that is a quota and not a throttle: the sentence, and the figures behind it.
object
What was reached and the way out.
object
The ceiling. A write that would take used past it is refused with 429.
What the project holds now, counted by the same query that refuses a write.
limit - used, never below 0.
When the oldest counted run ages out of the rolling 24 hours and a slot frees on its own. null for the two quotas only an action frees (delete cases, decide queue items), and for a run quota with no runs in the window.
Examples
A throttle: no `quota`; wait `Retry-After`
{ "error": "rate limit exceeded — slow down"}A quota (#2458): the MCP server ceiling; `resetsAt` is null, nothing frees it by waiting
{ "error": "MCP server quota reached — at most 50 servers per project, and a server cannot be removed yet. Ask an operator to raise the limit.", "quota": { "kind": "mcpServersPerProject", "limit": 50, "used": 50, "remaining": 0, "resetsAt": null }}Headers
Section titled “Headers ”Seconds until the window rolls over on a throttle; on a quota, until quota.resetsAt — sent only for the run quota, which has one