# Approve a request to connect an agent

> Page: https://docs.plotwork.dev/api/post-user-mcp-approve. Index of every page: https://docs.plotwork.dev/llms.txt

Verifies the signed authorization request the MCP server made, makes a hidden API key for the agent, and answers with a signed approval that carries the key sealed.

`POST /user/mcp/approve`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Approve a request to connect an agent. |
| What does it take? | A JSON body of type [`ApproveConnectionBody`](https://docs.plotwork.dev/api/schemas.md#approveconnectionbody). |
| What does it return? | Status 200 with a body of type [`Approval`](https://docs.plotwork.dev/api/schemas.md#approval). |
| What can go wrong? | `400` the request is malformed, has expired, or was not signed by the mcp server; `401` not signed in; `403` the request came from an origin that may not make changes, you are a reader in the organisation (orgs.forbidden), the organisation requires single sign-on (orgs.sso_required), or an organisation asks that agents connect to it (mcp.org_connection_required); `404` no such organisation, or you are not a member of it; `429` too many requests; `503` connecting an agent is not set up on this server. Every failure uses the one error envelope. |

## What it does

Verifies the signed authorization request the MCP server made, makes a hidden API key for the agent, and answers with a signed approval that carries the key sealed. The browser then goes to redirectTo. With organisation, the key belongs to that organisation and acts as you, with your role's diagram permissions; a reader may not. Connecting the same agent install again replaces its key.

## Request body

The body has the type [`ApproveConnectionBody`](https://docs.plotwork.dev/api/schemas.md#approveconnectionbody).

| Field | Type | Required | Description |
|---|---|---|---|
| `request` | `string` | yes | The signed authorization request, exactly as the MCP server put it in the address. at least 1 character; at most 6144 characters. |
| `organisation` | `string` | no | Connect the agent to this organisation, by its id, instead of your own account. Any role but reader may. The agent then works in the organisation's library as you, with the diagram permissions your role has and nothing more, and its calls count toward your own daily allowance. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | Approved. | [`Approval`](https://docs.plotwork.dev/api/schemas.md#approval) |
| 400 | The request is malformed, has expired, or was not signed by the MCP server. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 401 | Not signed in. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 403 | The request came from an origin that may not make changes, you are a reader in the organisation (orgs.forbidden), the organisation requires single sign-on (orgs.sso_required), or an organisation asks that agents connect to it (mcp.org_connection_required). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 404 | No such organisation, or you are not a member of it. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 503 | Connecting an agent is not set up on this server. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 200 answer has the type [`Approval`](https://docs.plotwork.dev/api/schemas.md#approval).

| Field | Type | Required | Description |
|---|---|---|---|
| `approval` | `string` | yes | The signed approval. It carries the connection key sealed, so it is safe in an address. |
| `expiresIn` | `integer` | yes | Seconds the approval stays usable. |
| `redirectTo` | `string` | yes | Where to send the browser: the MCP server callback with the request and the approval already attached. |

## See also

| Doc | Why |
|---|---|
| [API reference](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |