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

# Plan limits

> Which Admin API tools and endpoints are refused when your workspace is at its plan limit, the plan-limit error returned on MCP (structuredContent.planLimit) and REST (403 with a planLimit body), what each field means, and how to raise a limit.

Your MCP Manager plan sets how many servers, gateways and roles a workspace can have, and which advanced features it includes. The Admin API enforces those limits exactly as the app does. A create, enable or restore that would take the workspace past its plan is refused with an error that names the limit, the current count, and how to resolve it.

> [!NOTE]
>
> **Closed beta.** The MCP Manager Admin API and MCP server are available now to a
> limited set of workspaces through the **MCP Manager Admin API** entitlement
> (`ff-mcpm-admin`), ahead of general availability. If you don't see **Settings →
> MCP & API** in your workspace, it isn't enabled for you yet — ask your MCP Manager
> contact to join the beta.

## What is limited

| Limit | Counts | Refused when |
| - | - | - |
| **Servers** | Enabled inbound MCP servers. Disabled and deleted servers don't count. | Creating, enabling, or restoring a server at the limit |
| **Gateways** | Enabled gateways. Disabled and deleted gateways don't count. Archiving a gateway disables it, so an archived gateway doesn't count either. | Creating, enabling, or restoring a gateway at the limit |
| **Roles** | Every role, **including the three built-in roles** (Administrator, Member, Super admin) | Creating or restoring a role at the limit |
| **Presidio rules** | Plan feature | Adding a Presidio rule, converting a rule to Presidio, or re-enabling one |
| **Custom rule engines** | Plan feature | Registering or restoring a rule engine, or adding, converting or re-enabling a rule that uses one |
| **Workstation servers** | Plan feature | Creating or restoring a workstation server |
| **OpenTelemetry forwarding** | Plan feature | Configuring a collector where none is configured |

Everything you already have stays, even if the workspace is over a limit, for example after a plan change, and it keeps working with one exception: Presidio rules do not run on a plan without Presidio. Each one is skipped, or blocks the call when its failure mode is block. Renaming, editing, disabling and deleting are never refused. Only adding more is.

Re-enabling or restoring a policy that still holds an enabled Presidio rule counts as adding one, so it is refused as a whole on such a plan. The same goes for an enabled custom-engine rule on a plan without custom rule engines. To save the policy's other rules, remove that rule or switch it to regex, then try again.

User seats are not limited by the Admin API.

If MCP Manager can't read the workspace's plan when you make a change, the change is allowed rather than refused, so a workspace can end up over a limit. What you have keeps working; only the next addition is refused. Don't treat a successful create as proof that there is room for another.

## Tools and endpoints that can be refused

* `create_inbound_server`, `enable_inbound_server`
* `create_gateway`, `enable_gateway`
* `create_role`
* `register_rule_engine`
* `add_gateway_rule` and `enable_gateway_rule`, when the rule uses Presidio or a custom rule engine
* `update_gateway_rule`, when it switches a rule to Presidio or a custom rule engine
* `set_otel_configuration`

The same limits apply in the app, so a refusal doesn't depend on where you make the change.

## The plan-limit error

Both surfaces return the same `planLimit` object.

**MCP.** The tool result has `isError: true`. Its text content is the plain-language message followed by the `planLimit` fields as JSON, and `structuredContent.planLimit` carries the same fields:

```json theme={null}
{
  "isError": true,
  "content": [{ "type": "text", "text": "This workspace has reached its plan limit of 10 enabled gateways (10 in use), so this gateway cannot be created. Disable or delete an existing gateway, or raise the limit by upgrading the plan in Settings → Plan & Usage (or ask your account manager).\n\n{ \"code\": \"PLAN_LIMIT_REACHED\", … }" }],
  "structuredContent": {
    "planLimit": {
      "code": "PLAN_LIMIT_REACHED",
      "resource": "gateways",
      "entitlementKey": "Workspace.McpOutboundGateways",
      "action": "create",
      "limit": 10,
      "currentCount": 10,
      "requested": 1,
      "message": "This workspace has reached its plan limit of 10 enabled gateways (10 in use), …",
      "correlationId": "9f1c…"
    }
  }
}
```

**REST.** The response is `403 Forbidden` with the standard error envelope plus `planLimit`:

```json theme={null}
{
  "error": "Forbidden",
  "message": "This workspace has reached its plan limit of 10 enabled gateways (10 in use), …",
  "statusCode": 403,
  "correlationId": "9f1c…",
  "planLimit": { "code": "PLAN_LIMIT_REACHED", "resource": "gateways", "limit": 10, "currentCount": 10, "…": "…" }
}
```

### Fields

| Field | Meaning |
| - | - |
| `code` | `PLAN_LIMIT_REACHED`: a numeric limit is exhausted. `PLAN_FEATURE_UNAVAILABLE`: the plan doesn't include the feature. |
| `resource` | What was limited: `servers`, `gateways`, `roles`, `presidio_rules`, `integration_rule_engines`, `workstation_servers`, or `otel_collector`. |
| `entitlementKey` | The plan entitlement behind the limit, for example `Workspace.McpOutboundGateways`. |
| `action` | What was refused: `create`, `enable`, or `restore`. |
| `limit` | The plan's limit. `null` for a feature. |
| `currentCount` | How many the workspace has now. `null` for a feature. |
| `requested` | How many the call tried to add. Usually `1`; absent for OpenTelemetry. |
| `message` | The plain-language explanation that starts the text content. |
| `correlationId` | Quote it to support to trace the request. |

An agent should branch on `code` and `resource`, not on the message text. The message wording may change; the fields will not.

## How to resolve it

* **Make room.** Disable or delete a server or gateway you no longer use, or delete a custom role you no longer use. Disabled servers and gateways don't count toward the limit.
* **Raise the limit.** Upgrade the plan in **Settings → Plan & Usage** in the app, or ask your MCP Manager account manager to add capacity or the feature. A plan change takes effect on your next call; there is no delay to wait out.

On the Core and Plus plans, the role limit equals the three built-in roles, so creating a custom role needs a plan with more role capacity.

## Further reading

> [card] [Authentication & access](https://docs.mcpmanager.ai/admin-api/authentication.md)
>
> Entitlement, capability gating, and every status code the API returns.

> [card] [Tool & endpoint reference](https://docs.mcpmanager.ai/admin-api/reference/overview.md)
>
> Every operation with its MCP tool name, REST route, and required capability.


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