Add an MCP server
const url = 'https://beta-api.plune.ai/v1/mcp-servers';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"Shop MCP","transport":"stdio","description":"The shop’s order tools"}'};
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 \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "Shop MCP", "transport": "stdio", "description": "The shop’s order tools" }'A person, or a write token without X-Plune-Session (CI). An agent is refused (403 agent_proposes). A name is the project’s once, whatever its case (409 server_exists). A project holds at most 50 servers (429, body { error, quota: { kind: 'mcpServersPerProject', limit, used, remaining, resetsAt: null } }; a server cannot be removed yet). The catalog keeps which server and how it is reached, never where: an address, command, header or variable is refused (400). Logged as an update of the project.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”A name, how the server is reached, and a line for people. Nothing else is accepted: there is no field for an address, command, header or variable. The name and the line are free text, kept as sent.
object
Example
{ "name": "Shop MCP", "transport": "stdio", "description": "The shop’s order tools"}Responses
Section titled “ Responses ”The server
object
The project’s once, whatever its case
How the server is reached. Not where: the catalog has no field for an address, command, header or variable
How it came into the catalog: manual - a person added it; mission - an mcp source of a mission named it, and the catalog took it in at once
confirmed - a person added it; derived - inferred from a mission source. A mission source that names a server already here links it and leaves its trust as it was
The mission source that named it; null for a server no source names, and once that source is taken off (the server stays)
Tools the latest snapshot lists
Snapshots taken; also the number of the latest
Example
{ "id": "6f1c2b3a-0000-4000-8000-000000002458", "projectId": "u-shop::default", "name": "Shop MCP", "transport": "stdio", "description": "The shop’s order tools", "source": "manual", "trust": "confirmed", "missionSourceId": null, "tools": 0, "snapshots": 0, "createdBy": "6f1c2b3a-0000-4000-8000-0000000000a2", "createdAt": "2026-11-13T09:00:00.000Z", "updatedAt": "2026-11-13T09:00:00.000Z"}Invalid JSON or body
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"}The project has an MCP server of this name (server_exists)
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