> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usepatchwork.co/llms.txt
> Use this file to discover all available pages before exploring further.

# The MCP grant object

> One user's standing authorization for one MCP client on one agent. List them, revoke them.

When a user connects an agent from their own AI client, our consent screen records a grant. It is the standing authority behind every later `tools/call` — see [MCP export](/guides/mcp).

Because the grant lives with us, you manage it through us. Both endpoints take your workspace API key, and neither is gated on credits: you must always be able to cut off access.

## The object

```json theme={null}
{
  "id": "2c5ea4c0-4067-11e9-8bad-9b1deb4d3b7d",
  "subject_ref": "user_9f2",
  "scopes": ["read", "write"],
  "agent": {
    "public_id": "agent_4f3ca81b9d2e7f60…",
    "name": "Support assistant"
  },
  "client": { "name": "Cursor" },
  "created_at": "2026-10-09T14:22:05Z",
  "last_authorized_at": "2026-10-09T16:04:11Z"
}
```

<ResponseField name="id" type="uuid">
  Pass to the delete endpoint to revoke.
</ResponseField>

<ResponseField name="subject_ref" type="string">
  The subject your [login bridge](/guides/mcp-login-bridge) asserted. Every run made under this grant carries it.
</ResponseField>

<ResponseField name="scopes" type="string[]">
  What the client asked for and the user allowed — `read`, `write`, or both. Recorded for your audit; what the client can actually call is set by the agent's wiring. See [Scopes](/guides/mcp#scopes).
</ResponseField>

<ResponseField name="agent" type="object">
  The exact published agent version this grant is for. A grant never spans agents.
</ResponseField>

<ResponseField name="client" type="object">
  The MCP client's registered name, as it introduced itself. Treat it as a label, not an identity.
</ResponseField>

<ResponseField name="created_at" type="string">
  When the user first consented.
</ResponseField>

<ResponseField name="last_authorized_at" type="string">
  When an access token was most recently issued against the grant. `null` if none ever was. This tracks re-authorization, not tool calls — read [requests](/guides/requests) with `origin: "mcp"` for activity.
</ResponseField>

## Unique per subject, agent and client

The same user connecting the same agent from the same client twice updates one grant rather than accumulating them. Connecting from a second client, or to a second agent, is a second grant.

## Revoking

```bash theme={null}
curl -X DELETE https://api.usepatchwork.co/v1/mcp/grants/2c5ea4c0-… \
  -H "Authorization: Bearer sk_…"
```

Revoking marks the grant and expires every access token issued against it. The client may still hold a token it believes is live; it stops working at our door on its next call. Nothing already finished is undone.

Only grants in your own workspace are visible or revocable. Listing returns active grants, newest first, [cursor-paginated](/api-reference/index#pagination); pass `subject` to narrow to one user.

## Errors

| Code | Status | When |
| - | - | - |
| `unauthorized` | `401` | Missing or invalid API key. |
| `not_found` | `404` | No grant with that id in this workspace. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.