Skip to main content

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.

The hardest part of running MCP safely is identity: knowing exactly whose authority a tool call carries, and making sure each downstream MCP server only ever sees what that person is allowed to see. MCP Manager is built around this problem. It authenticates every caller, brokers the right credential to each upstream server, stores those credentials encrypted, and attributes every action to a real identity in your logs.
Managing other people’s identities and credentials is gated by capabilities; managing your own identities is always available to every user. The Identity management capability covers updating identity availability, enabling and disabling identities, and deleting identities created by others. Setting a server’s identity scheme on a gateway is part of Basic gateway management, and creating server identities is part of Basic server management. If you don’t see a control described here, your role lacks the relevant capability — capabilities are assigned per role and fully configurable, so access depends on the capability, not on any fixed role name. See the capabilities reference.

​
Why identity is the hard problem in MCP

A common misconception is that an identity provider solves MCP identity. An IdP such as Okta or Entra ID grants access to the app — it gets a person into Claude or ChatGPT. It says nothing about whether a request that app makes to your GitHub or Snowflake server should run as that person, and with their permissions. MCP leaves that second hop entirely undefined. Worse, the easiest way teams fill the gap is the most dangerous: a long-lived token pasted into a config file on a laptop, shared by everyone and attributable to no one. MCP Manager closes the gap by treating identity as a first-class object that lives between the client and each server, and by keeping the two authentications that matter strictly separate.

​
Two separate authentications

A gateway brokers identity, so there are two distinct authentications on every call, and decoupling them is what makes per-user access possible. Do not picture a single auth arrow from client to server.
  • Client → gateway is uniform: every client authenticates to the gateway the same way — OAuth delegated to your organization’s SSO, or a gateway API token for a headless agent.
  • Gateway → upstream varies per server: the gateway independently presents the right credential to each upstream server.
This separation is covered from the gateway’s side in Two separate authentications. This page is about the second hop — the identities the gateway brokers upstream.

​
Per-user identity versus shared identity

Whether a given server uses each caller’s own credential or one shared credential is the server’s identity scheme on that gateway, set by an administrator when assigning the server. The choice is the difference between individual accountability and shared convenience.
  • Per-user identity (bring your own identity). Every user authenticates individually, so the downstream server enforces that user’s own permissions and every action is attributed to the real person. This is the foundation of least privilege and non-repudiation in MCP Manager: an analyst reads and writes only what they are entitled to, and the log names them.
  • Shared identity. A single pre-selected credential — typically a bot or service account — is used by everyone on the gateway. Choose this deliberately, when individual attribution isn’t required or the downstream system has no per-user concept.
A powerful pattern falls out of this: you can add the same server to a gateway twice — once with a shared identity exposing only read and search tools, and again requiring each user’s own identity for the write tools — so reads are frictionless while every write carries individual accountability. See Adding the same server more than once.

​
Private and Global availability

Each identity also has an availability that controls who may select it, independent of the scheme above:
  • Private — usable only by the person who created it. This is the default and suits personal accounts and individual tokens.
  • Global — shared, so others in your organization can use it (for example, a service account behind a shared-identity scheme). Identities created before this setting existed behave as Global.
A Private identity is never selectable by anyone but its owner — even an administrator with the View all identities capability cannot use it. That capability is a read-only governance preview: it lets an administrator see which identities exist and what access they would expose, without the ability to act as another user. The full model lives in How identities control access across all three server types.

​
How MCP Manager authenticates to a server

When you add a server, MCP Manager first attempts standard OAuth automatically; if the server can’t connect that way, you choose one of the other two methods. Every method ends the same way: MCP Manager holds the credential, encrypted, and attaches it to each request it makes on your behalf. Servers fall into three authentication shapes — OAuth, token, and open (no authentication) — described below.

​
Standard OAuth with dynamic client registration

The most seamless method, and the one MCP Manager tries first. You provide only the server’s URL, and MCP Manager runs the entire flow for you: it discovers the server’s OAuth metadata, registers itself as a client dynamically (no app to create in a developer portal), redirects you to authorize with PKCE, and then manages token refresh going forward. The authorization callback returns to a fixed MCP Manager URL:
Callback URL
https://mcp.mcpmanager.ai/api/v1/mcpm/inbound/oauth/callback
Atlassian’s MCP server is a good example of a server that supports this method. When it works, connecting a server is as simple as pasting a URL and approving a consent screen.

​
OAuth with client pre-registration

Some servers require you to create an application in their developer portal first, then authorize against it. You register an app with the provider, give MCP Manager the resulting Client ID and Client Secret, and enter the callback URL above in the provider’s app settings. Once configured, token exchange and refresh work exactly like the standard method. Use this when automatic OAuth doesn’t work — because the server requires clients to be registered ahead of time, doesn’t support dynamic client registration, or only allows an allowlist of well-known clients. Asana, HubSpot, and Slack are common examples.

​
Token in custom headers

When a server authenticates with an API key or bearer token rather than OAuth, you provide the credential directly as one or more custom headers. You enter the header name (for example, Authorization) and value (for example, Bearer your-token-here), and MCP Manager attaches them to every request it sends to that server. Token authentication is often more stable and lets you scope the token when you create it; the trade-off is that you generate the token yourself in the provider’s settings.
Some servers accept more than one method — GitHub takes both OAuth and header tokens. Token auth tends to be more stable and scopable; OAuth is usually friendlier for non-technical users. For how to choose per server, see How to choose an authentication method.

​
Where credentials live and how they’re protected

Every credential you provide and every OAuth token MCP Manager obtains for you is encrypted with AES-256-GCM and stored in MCP Manager’s secure key vault. Credentials are never exposed in logs and are not accessible to other users — a Private identity’s secret is unreadable even to administrators. Because credentials live in the gateway’s vault rather than in mcp.json files on individual machines, the long-lived-token-on-a-laptop exposure that causes real-world breaches is removed: there is one encrypted, centrally revocable store instead of copies scattered across endpoints.

​
Token lifecycle: refresh, rotation, and revocation

MCP Manager refreshes OAuth tokens automatically, so connections keep working without users re-authenticating, and it deduplicates concurrent refreshes so a burst of simultaneous calls (for example, after a workstation wakes from sleep) doesn’t race and revoke each other. It also supports automated token rotation to keep credentials fresh. Revocation is immediate and lives at several layers, each an enabled toggle checked on every request:
  • Disable an identity to stop every call that would use that credential.
  • Disable a connection between a host and a gateway to cut that specific link.
  • Disable a host (an app or agent) to block everything it does, without deleting its tokens.
Re-enabling restores access instantly; nothing is deleted in the meantime. This is the “break glass” control for an incident, an offboarding, or a suspicious agent.

​
Edge and failure behavior

  • Token expiry that can’t be refreshed surfaces as a 401 from the upstream server, propagated back to the caller so they can re-authorize — the gateway does not silently swallow it.
  • A disabled identity, connection, or host causes the call to be rejected before it reaches the server, with an alert recorded.
  • A shared-identity server with no identity selected returns a clear error directing an administrator to set the shared identity on that server within the gateway.

​
Attribution: every action ties back to a real identity

Because the gateway brokers a specific identity on every upstream call and logs each hop, your audit trail attributes each action to the user (and the app or agent) behind it — user_name, user_email, and user_guid are recorded alongside the server, tool, and identity used. Per-user identity schemes make this attribution meaningful end to end: the downstream system sees the real person, and so does your log. See Viewing Logs and Audit & Observability.

​
Headless agents and per-user tokens

Agents with no human at a browser authenticate to a gateway with an API token rather than OAuth. The advanced — and most powerful — pattern lets a single agent serve many end users while still using each user’s own downstream credential: every user enrolls once and brings their identity, MCP Manager mints them a per-user token, and the agent presents the right user’s token on each call so the downstream server acts as the real person. The full design, including the runtime sequence, is in Agents that Pass Identities to MCP Manager.

​
Further reading

Feature Governance

The next security layer — least privilege over which tools a gateway exposes.

The identities model

Private and Global availability, and per-user versus shared identity schemes, across all server types.

Remote server authentication

How to choose between the three authentication methods when connecting a server.

SSO

Delegating client-to-gateway authentication to your organization’s identity provider.

​
External sources

MCP authorization spec

The OAuth 2.1-based authorization model defined by the Model Context Protocol.

OAuth 2.1

The authorization framework behind MCP’s OAuth flows.