Skip to content

Take a snapshot of an MCP server’s contract

POST
/v1/mcp-servers/{id}/snapshots
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.

id
required
string

The server’s id

Media type application/json

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
kind

What the CLI’s file calls itself; not stored

string
Allowed values: plune-mcp-snapshot
schemaVersion

The CLI file’s version; not stored

integer
Allowed values: 2
transport

The connection of the CLI’s file; not stored - the server’s transport is the server’s

string
Allowed values: stdio http sse
environment

Where the server was running. Not part of the contract and not of its hash

string
>= 1 characters <= 100 characters
server
object
name
required
string
version
required
string
title
string
instructions
string
nullable <= 20000 characters
capabilities

As the server declared them

object
tools

A name is listed once

Array<object>
nullable <= 500 items
object
name
required
string
title
string
description
string
inputSchema
object
outputSchema
object
annotations
object
execution
object
x-plune

Contract fields of Plune’s own server: visibility (core or discoverable) and write

object
resources

Entries of resources/list: uri, and name, title, description, mimeType

Array<object>
nullable <= 2000 items
object
resourceTemplates

Entries of resources/templates/list: uriTemplate, and name, title, description, mimeType

Array<object>
nullable <= 2000 items
object
prompts

Entries of prompts/list: name, and title, description, arguments

Array<object>
nullable <= 2000 items
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"
}
}
}
}
]
}

The same contract as the latest snapshot’s: that snapshot, unchanged

Media type application/json

A snapshot of a server’s contract. Never changed after it is written.

object
id
required
string
projectId
required
string
serverId
required
string
number
required

Counts from 1 within the server

integer
>= 1
hash
required

SHA-256 of the canonical JSON of the contract (keys sorted at every level): the same contract has the same hash

string
environment
required

Where the server was running when it answered. Not part of the contract and not of its hash

string
nullable
tools
required

Tools listed; null when the server declares no tool list. 0 is a list that holds nothing

integer
nullable
createdBy
required
string
createdAt
required
string format: date-time
content
required

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
server
required
object
instructions
required
string
nullable
capabilities
required
object
tools
required
Array<object>
nullable
object
resources
required
Array<object>
nullable
object
resourceTemplates
required
Array<object>
nullable
object
prompts
required
Array<object>
nullable
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

Media type application/json

A snapshot of a server’s contract. Never changed after it is written.

object
id
required
string
projectId
required
string
serverId
required
string
number
required

Counts from 1 within the server

integer
>= 1
hash
required

SHA-256 of the canonical JSON of the contract (keys sorted at every level): the same contract has the same hash

string
environment
required

Where the server was running when it answered. Not part of the contract and not of its hash

string
nullable
tools
required

Tools listed; null when the server declares no tool list. 0 is a list that holds nothing

integer
nullable
createdBy
required
string
createdAt
required
string format: date-time
content
required

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
server
required
object
instructions
required
string
nullable
capabilities
required
object
tools
required
Array<object>
nullable
object
resources
required
Array<object>
nullable
object
resourceTemplates
required
Array<object>
nullable
object
prompts
required
Array<object>
nullable
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

Media type application/json
object
error
required
string
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)

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

No such MCP server in your project

Media type application/json
object
error
required
string
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.

Media type application/json
One of:
object
error
required
string
Examples

A throttle: no `quota`; wait `Retry-After`

{
"error": "rate limit exceeded — slow down"
}
Retry-After
integer

Seconds until the window rolls over on a throttle; on a quota, until quota.resetsAt — sent only for the run quota, which has one