Skip to main content
Every Admin API request carries a bearer credential and passes three checks in order: the workspace entitlement, then the credential’s authenticity, then the operation’s capability. This page is the reference for each credential type, the entitlement, capability gating, and the status codes the API returns.
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.

​
Credential types

The Admin API accepts a bearer token in the Authorization header on both the MCP and REST surfaces. The token is either a Personal Access Token or an OAuth 2.1 access token; the server tells them apart by prefix — a credential beginning with mcpm_pat_ is verified as a Personal Access Token, and anything else is verified as an OAuth JWT.

​
Personal Access Tokens

A Personal Access Token (PAT) is a long-lived credential you mint for a headless agent or pipeline. Create, list, and revoke them at MCP & API → Tokens or with the create_access_token / list_access_tokens / revoke_access_token operations. The plaintext secret is returned once, at creation. Because only its SHA-256 hash is stored, MCP Manager cannot show it again — losing it means minting a new token. Each token’s last-used time is tracked (best-effort, updated at most once every 5 minutes) so you can spot dormant tokens. Creating a token is idempotent by label. If you already hold a valid token with the same label, create_access_token returns that token’s metadata with alreadyExisted: true and token: null — the existing secret is never re-shown — rather than minting a duplicate. Choose a new label when you genuinely need a fresh secret. This lets a provisioning pipeline re-run safely without accumulating duplicate tokens. Revocation is immediate and scoped to you. Revoking a token stops it working on the next call and removes it from your list. You can only revoke your own tokens; a request to revoke a token you don’t own returns 404.

​
OAuth 2.1 access tokens

Interactive MCP clients can authenticate with OAuth 2.1 instead of a Personal Access Token. The admin MCP server is an OAuth protected resource: a client that lacks a credential receives a 401 whose WWW-Authenticate header advertises the protected-resource metadata document per RFC 9728 (OAuth 2.0 Protected Resource Metadata), and the client then runs the authorization flow to obtain a bearer. Access tokens are audience-bound to the admin MCP resource following RFC 8707 (Resource Indicators for OAuth 2.0): the token’s aud claim must include the resource ${ROOT_URL}/mcpm-admin/mcp. A token minted for a different resource is rejected, so an OAuth token issued for one endpoint cannot be replayed against the Admin API. The token’s sub claim carries the resolved MCP Manager identity, which supplies the user, role, and capabilities for the request.

​
The MCP Manager Admin API entitlement

Access to the entire Admin API — every tool and endpoint, and the Settings → MCP & API area in the app — is gated by the MCP Manager Admin API entitlement (ff-mcpm-admin) on your workspace. This is a plan-level feature, not a role capability, so it is checked before anything else on every request.
  • A workspace without the entitlement receives 403 Forbidden — “This organization is not entitled to the MCP & API configuration layer.”
  • If the entitlement check itself can’t be completed (an upstream lookup fails), the API returns 503 Service Unavailable — “Entitlement check failed” — rather than silently allowing or denying the call. The check fails loud.
If you can reach the app but the MCP & API settings area is missing, your workspace isn’t in the beta. Access depends on the entitlement, not on any role — ask your MCP Manager contact to enable it.

​
Capability gating

Once a request is entitled and authenticated, each operation enforces the same capability as the equivalent action in the app. The Admin API never widens what your role permits: if you couldn’t do something by hand in the UI, the corresponding tool or endpoint refuses it.
  • Most operations require a specific capability — for example, creating a server requires Basic server management, querying logs requires View and export logs, and editing a role requires Manage roles.
  • A few operations require no capability and are available to any authenticated caller: whoami, list_capabilities, and managing your own access tokens (create_access_token, list_access_tokens, revoke_access_token).
  • A call you lack the capability for returns 403 Forbidden — “Capability ‘<key>’ is required.”
Call list_capabilities to retrieve every capability key, grouped as it appears in the product, with a label and description — useful before building a role’s grants with create_role or modify_role. Each entry in the tool & endpoint reference names the capability it requires. For what each capability allows, see the capabilities reference.

​
Response status codes

The REST surface returns standard HTTP status codes; the MCP surface surfaces the same failures as tool errors. Every response carries a correlation id you can quote when asking support to trace a request.

​
What is and isn’t exposed

The Admin API is deliberate about secrets. These properties hold across every operation:
  • Token secrets are write-only. A Personal Access Token’s secret is shown once and stored only as a SHA-256 hash.
  • Credential and integration header values are write-only. Identity header tokens and OpenTelemetry collector headers are stored encrypted; read operations return header names only, never their values.
  • Alert debug context is scrubbed at write time. Sensitive keys — authorization, cookie, set-cookie, access_token, refresh_token, client_secret, password, and similar — are replaced with [REDACTED] before an alert is stored, so get_alert never surfaces a live secret.

​
Further reading

Tool & endpoint reference

Every operation with the capability it enforces and its MCP tool name and REST route.

Connect an agent

Create a token and register the admin MCP server in your client.

Capabilities

What each capability allows, grouped exactly as the Admin API groups them.

Authentication & Identity

How MCP Manager stores and brokers the credentials behind every identity.

​
External sources

RFC 8707 — Resource Indicators for OAuth 2.0

The audience-binding standard the admin server enforces on OAuth access tokens.

RFC 9728 — OAuth 2.0 Protected Resource Metadata

The metadata document the 401 challenge advertises so clients can discover the authorization server.