Skip to main content
External authentication is available on Developer and Enterprise.
External authentication controls the credential that FastMCP Gateway sends to a downstream service. The MCP client first proves who the caller is to FastMCP Gateway. FastMCP Gateway then sends an OAuth token or the configured authentication headers for that caller, or sends no credential when a remote MCP server accepts anonymous requests. For credential-based modes, an external auth configuration is the saved definition for that second credential. The FastMCP Gateway dashboard presents it as an auth source. It records how to acquire and inject credentials, while each user’s OAuth grant or API key is stored separately. The no-authentication mode does not create an auth source. FastMCP Gateway uses external auth configurations in two places: The two credentials serve different trust boundaries: For the first boundary, see Authentication. Server roles and capability policies are covered in Authorization.

​
Authentication modes

Choose the mode based on whether the downstream provider requires a credential and who owns that credential. No authentication applies only to external servers. FastMCP Gateway still authenticates and authorizes the caller at the FastMCP Gateway endpoint, but it does not forward the caller’s FastMCP Gateway credential to the remote MCP server.
Select no authentication only when the remote MCP server accepts anonymous requests. FastMCP Gateway sends no downstream Authorization header in this mode.
OAuth and per-user API keys preserve the downstream user’s identity and permissions. A shared API key makes every forwarded request act as the same upstream principal, even though FastMCP Gateway continues to identify and authorize the original caller at its own gateway.
A shared API key gives every authorized caller the downstream permissions of the shared upstream principal. Scope that principal to only the access the server needs.

​
OAuth setup

FastMCP Gateway starts OAuth setup with the provider or remote MCP URL. It follows protected-resource and authorization-server metadata to locate the OAuth endpoints. When manual setup is required, register FastMCP Gateway’s callback URL with the provider, then enter the resulting client details in FastMCP Gateway. For the hosted FastMCP Gateway control plane, use https://horizon.prefect.io/oauth/external/callback. After the configuration is saved, each user completes the provider flow for their own FastMCP Gateway identity. External-server users can select Authorize from the server’s Connection page. Hosted-server users authorize when connecting an interactive MCP client, as described in User authorization. FastMCP Gateway stores the resulting credential for that FastMCP Gateway actor. The MCP client never receives the provider token.

​
API-key setup

An API-key auth source can send up to ten headers. Configure each header name, its value, and an optional encrypted credential in one editor. This supports providers that require an API key with an organization, tenant, or profile identifier. A header value can contain zero or one {token} placeholder: New headers default to {token} because a provider can treat an identifier as sensitive even when it is not called a secret. Use a literal value only when users who can view the auth configuration can also view that value. FastMCP Gateway never displays an encrypted credential after it is saved. For example, a provider can require two independent protected values:
Another provider can use an encrypted key with a visible identifier:
Use header injection for remote credentials. Query-string credentials are not a supported authentication channel. A secret embedded in a connector URL can appear anywhere that URL is displayed or recorded. With a per-user API key, each {token} value entered during setup belongs to the current user. Each additional user enters their own values for these headers. Literal values are part of the auth source configuration and apply to every user. With a shared API key, a server administrator saves one credential set for the organization.

​
External servers

An external server always authenticates the client at the FastMCP Gateway-served endpoint. FastMCP Gateway then uses the configured external credential, or no credential for a public remote MCP server, when it forwards the request.
1

Choose a connector

From Servers, start creating an external server. Select a global connector, or add and select an organization connector for the remote MCP endpoint.
2

Choose authentication

Enter the connector name, then select No authentication, OAuth (per user), Key (per user), or Key (shared). Select no authentication only when the remote server accepts anonymous requests.
3

Configure the provider

For OAuth, review the discovered registration or enter a pre-registered client. For an API key, add every required header and enter each encrypted value in the same form. FastMCP Gateway requires every token-backed value before it creates an external server.
4

Authorize OAuth

If you selected OAuth, complete Authorize with OAuth.
5

Create the connector

Review the remote endpoint and authentication mode, then select Create Connector. For a per-user or shared key, FastMCP Gateway saves the credential values when connector creation succeeds. FastMCP Gateway sends anonymous requests when you selected no authentication.
For OAuth and per-user API keys, every additional user must authorize the remote server separately. They can open the external server’s Connection page to authorize, replace, or revoke their credential. A user who has FastMCP Gateway server access but no valid remote credential can pass FastMCP Gateway’s access checks and still receive an authentication failure from the remote server.

​
Delegated authorization

Hosted delegated authorization applies the same external auth configuration to a hosted server. It is useful when hosted server code calls an upstream API as the signed-in user and already expects that provider’s token in an HTTP request header. The setup flow and runtime flow form a double handshake:
  1. The user authorizes FastMCP Gateway with the upstream provider, or stores a personal token in FastMCP Gateway.
  2. The MCP client authenticates to FastMCP Gateway. The trusted gateway identifies the FastMCP Gateway user, exchanges that identity for the saved downstream credential, and injects the credential before invoking hosted server code.
Setup Runtime On a successful exchange, FastMCP Gateway removes the inbound FastMCP Gateway Authorization header. It then injects every downstream header configured by the auth source. For the default OAuth configuration, hosted server code receives:
FastMCP Gateway completes the exchange before hosted server code runs and injects only the resulting downstream credential. Your code cannot access the auth source or other credentials stored in FastMCP Gateway. Code that already reads the configured header can use delegated authorization without implementing its own OAuth callback or credential storage.

​
Configure delegation

Delegated authorization requires FastMCP Gateway Authentication to remain enabled for the hosted server. Linking and unlinking an auth source updates serving configuration without rebuilding or redeploying the hosted server. The Access and Authentication page requires server write access, so these configuration steps are for a server administrator.
1

Open authentication

Open the hosted server, then select Access and Authentication. Confirm that FastMCP Gateway Authentication is enabled.
2

Link an auth source

In Delegated authentication, select Link auth source. Give the source a recognizable name and choose OAuth, per-user API key, or shared API key.
3

Configure credentials

For OAuth, enter the provider URL and select Discover. Review the Resource URL before saving, whether FastMCP Gateway registers the client automatically or asks for manual client details. For API keys, configure all headers and available credential values. Select Link auth source to save the configuration and attach it to the hosted server.
4

Add missing credentials

If you omitted credential values, select Authorize for OAuth, Add token for a per-user key, or Add key for a shared key. OAuth and per-user credentials belong to your signed-in FastMCP Gateway user. Shared credentials belong to the organization.
5

Test the exchange

Call the hosted server through its FastMCP Gateway endpoint as an authorized user. Confirm that the hosted handler receives the configured downstream headers and that its upstream call succeeds.
To correct a misconfigured OAuth source, open its action menu and select Edit Configuration instead of relinking. The dialog updates the authorization and token endpoints, the issuer, the resource URL, the requested scopes, and how the downstream token is sent. Stored OAuth client settings stay hidden and unchanged unless you select Replace OAuth client. When you replace the client, enter its client ID, token endpoint authentication method, and a new client secret for HTTP Basic or request body authentication. FastMCP Gateway replaces these settings together so they match the client registered with the provider. It does not use a client secret for no client authentication. Because saved tokens may no longer be valid for the new configuration, FastMCP Gateway discards them: every user authorizes again after the update, and the change reaches serving configuration without a rebuild. To stop delegated exchange, open the linked source’s action menu and select Unlink auth source. Unlinking disables delegated authorization for the hosted server and removes the saved link from serving configuration. Users must authorize again if the source is linked later.

​
Resource URL

An OAuth resource URL identifies the service the token may access. Your provider determines that value. Some providers use the hosted MCP server’s URL, while others require an upstream API URL. Check your provider’s OAuth documentation before setting it. Leave Resource URL blank when the provider does not require one. Protected-resource discovery can populate this value, while authorization-server discovery alone may omit it. During hosted auth-source setup, select Discover, then review Resource URL. You can edit or clear the value before selecting Link Auth Source. Clearing it saves the source without a resource, even if discovery provided one. To change a saved source, open Edit Configuration. For a hosted Prefect MCP server, use its complete serving URL, including /mcp. When the field is empty, select Use this server’s MCP URL to copy the hosted server’s Production serving URL into it. This fills the field without saving. The action is available during initial setup and later edits. If the serving URL is unavailable, enter the resource URL manually. If the auth source is shared, the resource URL must be valid for every linked server. Keep the Authorization Endpoint free of a manually added resource query parameter. FastMCP Gateway adds that parameter from the resource setting.

​
User authorization

OAuth and per-user API-key auth sources require every caller to save their own downstream credential. Users with server access do not need server write access to complete this authorization. An interactive MCP client starts the self-authorization flow when it first connects to the hosted server. After FastMCP Gateway sign-in, the FastMCP Gateway is requesting access page lists the linked auth source. Select Needs Access to complete OAuth or Needs credentials to save personal header values. FastMCP Gateway then completes the client connection. A client that uses a personal FastMCP Gateway API key does not open this browser flow. Before connecting that client, sign in to FastMCP Gateway in a browser and open:
Replace <server-slug> with the hostname prefix from the hosted server URL. For example, the slug in https://weather-mcp.fastmcp.app/mcp is weather-mcp. Authorize the provider or add the personal credentials, then retry the client. This self-authorization page requires server access, while auth-source configuration remains restricted to server writers. Service-account keys cannot use delegated authorization. Authorizing in the browser saves the downstream credential for the signed-in user, not the service account. Automation that authenticates with a service-account key must provide its upstream credential through the hosted server itself, such as with an environment variable, until service-account delegated authorization is supported. For user actors, a shared downstream API key needs no per-user authorization. FastMCP Gateway uses the organization-wide credential configured by the server administrator.

​
Current boundaries

Hosted delegated authorization has the following first-version boundaries: Fail-open behavior preserves hosted server availability when a credential is missing, expired, revoked, or temporarily unavailable. It does not bypass the initial FastMCP Gateway authentication or server access checks, which happen before the exchange. The hosted server will not receive a usable downstream credential, so its upstream call will normally fail authentication unless the server has an independent fallback. FastMCP Gateway encrypts OAuth client secrets, OAuth tokens, and API-key header values at rest. It keeps credential material out of normal responses, logs, and traces. For the storage and encryption boundary, see Data protection.

Authentication

Understand how callers authenticate to FastMCP Gateway before external exchange.

External servers

Register and operate remote MCP servers through the gateway.

Hosted servers

Build and run MCP servers that can use delegated authorization.

Data protection

Review how FastMCP Gateway protects credentials and other sensitive values.