Assign an MCP server to an agent

Gives the agent access to a server already registered with POST /api/mcp-servers. From the agent’s next conversation it can discover and call that server’s tools, under the server’s approval policy.

The assignment is refused when the agent has MCP tools disabled, when the server belongs to another agent (per-agent gateway rows), when the agent is still being provisioned, or when the plan’s cap on MCP servers per agent is reached (the platform’s own gateway never counts, and an already-assigned server answers 409 before the cap is checked). Hosted providers are attached to every agent automatically on create, so you normally only call this for custom servers or agents created later.

Side effects. Records the assignment and pushes the agent’s complete MCP server list to the voice engine. If that push fails, the assignment is rolled back and the error returned. Writes an agent.mcp.attach audit entry.

Idempotency. Safe to retry: a repeat call answers 409 MCP_ALREADY_ASSIGNED.

Webhook events. audit.log_recorded for the audit entry, if you subscribe to it. See Webhooks.

Access

Required scope: write. Any workspace role.
Rate limit: General API — 120 (Starter), 200 (Growth), 300 (Business) or 600 (Enterprise) requests/min per workspace. See Rate limits.
Plan: Requires an active subscription (active, trialing or past_due); without one the request is refused with 403 BILLING_ERROR (metadata.kind: subscription_required). Within the MCP-servers-per-agent cap: Starter 1, Growth 3, Business 10, Enterprise unlimited.

Authentication

AuthorizationBearer

Workspace API key: jl_ followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (Settings → API Keys) and sent as Authorization: Bearer jl_.... The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys.

Scope	GET / HEAD	POST / PUT / PATCH / DELETE	Admin-only routes
`read`	Yes	No	No
`write`	Yes	Yes	No
`full`	Yes	Yes	Yes

Operations restricted to admins or owners reject keys without the full scope with 403, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See Authentication.

Path parameters

agentIdstringRequiredformat: "uuid"

UUID of the agent. It must belong to the authenticated workspace; an id from another workspace answers 404, exactly like an unknown one. Returned as id by GET /api/agents.

Request

This endpoint expects an object.

mcpServerIdstringRequiredformat: "uuid"

The id of a workspace MCP server (from GET /api/mcp-servers).

Response

Assigned. The body carries a confirmation message only; read the list to see the server.

messagestring

Fixed confirmation text.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error

502

Bad Gateway Error