Skip to content

Add an MCP server

POST
/v1/mcp-servers
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.

Media type application/json

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
name
required
string
>= 1 characters <= 100 characters
transport
required
string
Allowed values: stdio http
description
string
>= 1 characters <= 500 characters
Example
{
"name": "Shop MCP",
"transport": "stdio",
"description": "The shop’s order tools"
}

The server

Media type application/json
object
id
required
string
projectId
required
string
name
required

The project’s once, whatever its case

string
transport
required

How the server is reached. Not where: the catalog has no field for an address, command, header or variable

string
Allowed values: stdio http
description
required
string
nullable
source
required

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

string
Allowed values: manual mission
trust
required

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

string
Allowed values: confirmed derived
missionSourceId
required

The mission source that named it; null for a server no source names, and once that source is taken off (the server stays)

string
nullable
tools
required

Tools the latest snapshot lists

integer
snapshots
required

Snapshots taken; also the number of the latest

integer
createdBy
required
string
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
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

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"
}

The project has an MCP server of this name (server_exists)

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