Skip to main content
These operations manage identities — the credentials MCP Manager uses to authenticate to a downstream server. A private identity is usable and editable only by its owner; its header token values are write-only and never returned.
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.

​
List Identities

Read-only List the credential identities attached to an inbound server. Returns each identity as { guid, name, enabled, accessControl, inboundServerGuid }. accessControl is ‘private’ (only the creator may use it) or ‘global’ (anyone in the org). The set is scoped to the server’s identities the caller is permitted to see. MCP tool: list_identities · REST: GET /api/v1/mcpm-admin/servers/:inboundServerGuid/identities · Capability: View all identities (accessAllIdentities) Parameters
​
inboundServerGuid
string
required
The guid of the inbound server whose identities to list (from list_inbound_servers).
Example

​
Add Identity

Add a credential identity to an existing inbound server. The server’s authenticationType selects the path:
  • Headers server — provide headers; a new credential identity is created and the headers stored encrypted. Returns the identity as { guid, name, enabled, accessControl, inboundServerGuid }.
  • OAuth server — supply the oauth* token fields for headless token injection (returns the server summary, authenticated after feature-learn validates the token), or omit them for the interactive flow (returns the server summary with an authorizationUrl to relay to the user for approval; the redirect callback then creates the identity). Do not pass headers to an OAuth server. On the interactive path the identity exists only after approval — once it does, you can wire it as the shared identity on a gateway assignment or select it when issuing a gateway token.
MCP tool: add_identity · REST: POST /api/v1/mcpm-admin/servers/:inboundServerGuid/identities · Capability: Identity management (identityManagement) Parameters
​
inboundServerGuid
string
required
The guid of the inbound server to add an identity to (from list_inbound_servers).
​
headers
object
Static request headers, as a name → value map. Required when the server uses headers auth. Header values are secrets — stored encrypted and never logged. mcpm- prefixed headers are reserved and dropped. (a string → string map)
​
oauthAccessToken
string
OAuth access token for headless token injection on an oauth server. Secret — never logged.
​
oauthRefreshToken
string
OAuth refresh token (optional) for headless token injection. Secret — never logged.
​
oauthExpiresAt
integer
Unix epoch milliseconds at which the access token expires (optional) for headless token injection.
​
oauthTokenEndpoint
string
The OAuth token endpoint URL, used to refresh the access token. Required for headless token injection.
​
oauthClientId
string
The OAuth client id. Required for headless token injection.
​
oauthClientSecret
string
The OAuth client secret (optional — confidential clients only). Secret — never logged.
​
oauthScope
string
Space-separated OAuth scopes granted to the token (optional) for headless token injection.
​
identityLabel
string
A name for the new credential identity. Defaults to “<server> Identity”.
​
accessControl
string
default:"private"
Who may use the credential: ‘private’ (only the creator) or ‘global’ (anyone in the org). Defaults to ‘private’. One of: private, global.
Example

​
Enable Identity

Enable a credential identity. Enables the identity. Saved only when the state changes. Returns the identity summary. A private identity you did not create is not visible. MCP tool: enable_identity · REST: POST /api/v1/mcpm-admin/identities/:identityGuid/enable · Capability: Identity management (identityManagement) Parameters
​
identityGuid
string
required
The guid of the identity to enable (from list_identities).
Example

​
Disable Identity

Disable a credential identity. Disables the identity so it can no longer authenticate. Saved only when the state changes. Returns the identity summary. MCP tool: disable_identity · REST: POST /api/v1/mcpm-admin/identities/:identityGuid/disable · Capability: Identity management (identityManagement) Parameters
​
identityGuid
string
required
The guid of the identity to disable (from list_identities).
Example

​
Delete Identity

Destructive Delete a credential identity. Permanently deletes the identity. Its encrypted header credential is not separately deleted (it lingers, org-scoped, and is never exposed). Returns { deleted: true, identityGuid }. MCP tool: delete_identity · REST: DELETE /api/v1/mcpm-admin/identities/:identityGuid · Capability: Identity management (identityManagement) Parameters
​
identityGuid
string
required
The guid of the identity to delete (from list_identities).
Example

​
Set Identity Availability

Set a credential identity’s availability (private or global). Changes whether the identity is private (creator-only) or global (usable/selectable by anyone in the workspace). CREATOR-ONLY: only the identity’s creator may change this, even with the view-all-identities capability. Returns the identity summary. MCP tool: set_identity_availability · REST: PATCH /api/v1/mcpm-admin/identities/:identityGuid/availability · Capability: Identity management (identityManagement) Parameters
​
identityGuid
string
required
The guid of the identity (from list_identities).
​
availability
string
required
‘private’ (only the creator may use it) or ‘global’ (anyone in the workspace may use/select it). One of: private, global.
Example

​
Set Identity Headers

Replace a credential identity’s header secrets. Sets (replaces) the encrypted header credentials for a header-authenticated identity. CREATOR-ONLY: only the identity’s creator may edit its secrets. Values are write-only — they are never returned by any tool. Returns the identity summary (header names/values are not included). MCP tool: set_identity_headers · REST: PUT /api/v1/mcpm-admin/identities/:identityGuid/headers · Capability: Identity management (identityManagement) Parameters
​
identityGuid
string
required
The guid of the identity whose header credentials to replace (from list_identities).
​
headers
object
required
The full set of request headers (e.g. an Authorization bearer) this identity sends upstream. REPLACES the existing set. Reserved ‘mcpm-’ and empty entries are dropped. Stored encrypted and never returned. (a string → string map)
Example

​
Further reading

Gateways

Where to go next in this section.

Authentication & access

Tokens, the entitlement, capability gating, and error codes for every operation here.

Tool & endpoint reference

The full reference index across every domain.

Capabilities

What each capability named on this page actually allows.