Skip to main content

Overview

With the MCP gateway, MCP clients reach remote MCP servers through a instead of connecting to them directly.
The Set up the MCP gateway recipe walks you through the listener, MCP servers, and network rule. See Recipes.
The gateway works with remote MCP servers that clients reach over HTTPS. It doesn’t cover local servers that clients start as a subprocess over stdio.
You add servers such as Linear or Notion to the Catalog, and each one gets its own address on the Connector:
MCP clients connect to that address and sign in with Formal. The Connector adds the upstream credential, enforces , and logs every tool call. Authentication happens on two sides, and you configure each one separately:

Upstream authentication

When you add a server, you choose which credential Formal sends to it. The admin Catalog offers three options:

Linked accounts (OAuth)

Each user links their own account for the server once. Formal stores the token encrypted in its control plane and refreshes it when the server supports refresh. The Connector adds the token to each request after policies allow it. Users never see the token. Users link accounts on the server’s page in the Catalog. They can also link during OAuth sign-in from an MCP client. Formal needs an OAuth client to sign users in to the server. Choose one under OAuth app:
You don’t register anything with the server. Formal identifies itself in one of two ways:
  • With an app Formal registered with the server’s provider, when there is one.
  • Otherwise, with a Client ID Metadata Document (CIMD), when the server supports it. The client ID is a URL where Formal hosts its name and redirect URI.
Formal checks the server when you save. If neither works, saving fails and asks you to use Your OAuth app.For CIMD, the server’s authorization server must:
  • Advertise client_id_metadata_document_supported: true.
  • Support the authorization code flow with PKCE S256.
  • Accept public clients, with token endpoint auth method none.
Linear, Notion, Sentry, Canva, Grafana Cloud, Fireflies, Exa, and Pylon met these requirements at the time of writing. To check another server, read its authorization server metadata:
Use this when Formal’s app doesn’t work with a server, or when users should see your own app on the provider’s consent screen.
  1. Register an OAuth app with the server’s provider.
  2. Copy the Redirect URI from the Catalog into the app’s allowed redirect URIs.
  3. Enter the app’s Client ID and, if it has one, its Client secret.
Formal encrypts the secret and never shows it again. Leave the secret empty for a public client, which uses PKCE alone.
To set OAuth scopes, use Permissions to request. Leave it empty to request the scopes the MCP server asks for, as the MCP authorization spec describes: the scopes in its sign-in challenge, or else the scopes its protected resource metadata lists. If it lists none, users get the server’s default access. You can change the scopes later. New scopes apply the next time each user links, and linked accounts keep what they were granted.
If you change the OAuth app, Formal unlinks every account and revokes every client approval for the server. Users must link and approve again.
If a user hasn’t linked an account, the Connector rejects their requests with a pointer to the server’s Catalog page. Linked accounts also work on HTTP, gRPC, and LLM resources. See OAuth and Linked Accounts, which also covers how the Connector picks the account for Endpoint and OIDC workload traffic.

Shared credentials

Formal adds one credential that you provide, such as an API key or a service account token. Users never see it. You store the credential as a native user on the server’s resource, and Formal sends the default one. To send different credentials to different people, add selection rules on the resource page. Use shared credentials for servers that accept API keys, or when everyone should act as one account.

Pass through

Clients send their own sign-in or API key, and Formal forwards it unchanged. Formal stores nothing. With pass through, the client’s own credential goes to the server, and nothing in the request identifies the Formal user. Formal can only attribute these requests when they come through the Formal Endpoint, which adds the user’s identity. For that reason, pass-through servers have no Connector address in the Catalog.

Downstream authentication

Clients identify the user to the Connector in one of two ways. Formal uses that identity for policies, logs, and choosing the upstream credential.

Formal OAuth

When upstream authentication isn’t pass through, the Connector acts as an OAuth protected resource:
  1. The Connector answers a request without a token with 401 Unauthorized. Its WWW-Authenticate header points to /.well-known/oauth-protected-resource.
  2. Formal is listed in that document as the authorization server.
  3. The client starts an authorization code flow with Formal. It identifies itself with its own CIMD URL, or with a client ID you pre-registered.
  4. The user signs in to Formal and approves the client on a Catalog consent screen. If the server uses linked accounts, the user links their account here too.
  5. Formal issues a short-lived access token bound to this server’s address, plus a refresh token.
The Connector validates access tokens offline and removes them before forwarding the request upstream. Formal rotates refresh tokens on each use and keeps them in its control plane. Every client must use PKCE S256. Formal’s authorization server doesn’t support Dynamic Client Registration (DCR). For a client without CIMD support, such as Cursor or Devin, pre-register it:
  1. Go to OAuth and open the Clients tab.
  2. Create a client with its name and exact redirect URIs. Make it confidential if it can keep a secret.
  3. Configure the client with the client ID and, if confidential, the secret. Formal shows the secret only once.
With Terraform, use formal_oauth_client. See Clients that can sign in for redirect URI rules. Users can review and revoke approved clients under Authorized apps in the Catalog account menu. Administrators can revoke any user’s approval on the OAuth page. After a revoke, Formal stops refreshing that client’s tokens, but access tokens already issued stay valid until they expire, within 15 minutes.

Identity headers

The Connector also accepts a Formal identity in two headers:
  • X-Formal-User-Username: the Formal username, such as idp:formal:human:alice@example.com
  • X-Formal-User-Password: a Formal-signed token for that user
The Formal Endpoint adds both headers for MCP clients on the device. Users keep the server’s original URL, such as https://mcp.linear.app/mcp. They don’t sign in again, because the Endpoint already knows who they are. To route Endpoint traffic to the gateway, create a network rule that forwards MCP traffic from AI agents to the Connector:
The rule matches requests from known agents when the destination is an MCP server in Formal. Checking the destination in pre_tls keeps Formal from terminating TLS on the agents’ other traffic. Servers you add later are covered without editing the rule. To cover other applications, widen the process conditions.

Deploy the Connector

Before you add servers, set up the following on the Connector:
  1. A listener that routes MCP traffic.
  2. A hostname.
  3. DNS and TLS that cover every subdomain of that hostname (i.e., *.<connector-hostname>), to enable smart routing. A request to linear.acme.connectors.joinformal.com routes to the server named linear.

1. Add an MCP listener

Create a listener with a Technology rule set to MCP. Use port 443 so client URLs don’t need a port.
  1. Go to Connectors and open your Connector.
  2. Add a listener on port 443.
  3. Add a rule with type Technology and technology MCP.
With a technology rule, the Connector routes every MCP server it can see. To expose only some servers, use Resource rules instead. See Listeners and Rules. A Connector in a Space only routes servers in that Space. A Connector without a Space routes all of them.

2. Add a hostname with wildcard DNS and TLS

Clients reach each server at a subdomain of the Connector hostname, so both DNS and the TLS certificate must cover *.<connector-hostname>.
Use a hostname ending in .<your-org>.connectors.joinformal.com. Formal creates both the hostname and wildcard DNS records. It also issues a wildcard certificate.
See Hostname and TLS Configuration for the full TLS options.
Claude and ChatGPT call MCP servers from Anthropic’s and OpenAI’s clouds. To use them, expose the Connector’s listener to the internet.
Verify:

Grant access to the Catalog

Users finish setup in the employee Catalog at catalog.formal.ai. There, they approve MCP clients during OAuth sign-in and link their upstream accounts. In Permissions, you control these calls through the Catalog application. If a permission uses default allow := false, add a rule for the Catalog to that same permission:
To limit the Catalog to one group, add a permission that denies everyone else:
Keep these constraints in mind:
  • Only active human users can approve an MCP client. Machine users authenticate with identity headers instead.
  • Administrators who add servers need the Mcp and Resource applications. To edit Access Controls on a server, they also need Policies.

Brand the Catalog

The Catalog can carry your organization’s name and logo. The header shows the name with the logo in place of the Formal mark, and the browser tab shows the same name and icon. A theme needs both, and the logo must be square since it is also the tab icon. Without a theme, the Catalog shows Formal’s own branding. Set them as code with the formal_org_theme Terraform resource, or through the OrgTheme API. Catalog users see the theme but can’t change it. In Permissions, the OrgTheme application controls who can.

Add an MCP server

  1. Go to Catalog and click Add MCP.
  2. Pick a template, or click Add Custom and enter the server’s URL.
  3. Enter a Name. Formal uses it as the server’s subdomain on the Connector.
  4. Choose the Space containing your Connector, such as default.
  5. Under Authentication, choose how Formal authenticates to the server. See Upstream authentication.
  6. Save the server.
Use a valid DNS label for the name: lowercase letters, digits, and hyphens, up to 63 characters. Formal can’t give a server with any other name a Connector address.
See the MCP servers catalog for every template, endpoint, and upstream authentication method. You can also create the server with Terraform. Set the mcp-endpoint tag to the server’s MCP path:
For linked accounts, add formal_resource_oauth_settings, a Linked Account native user, and a selection that picks it. The OAuth settings use Formal’s app unless you set upstream_oauth_mode = "pre_registered" with your app’s client_id and client_secret_wo:
The Catalog adds the native user and selection for you. Terraform doesn’t. See OAuth and Linked Accounts.
Changing resource_id, upstream_oauth_mode, client_id, or issuer replaces the settings, which unlinks every account. requested_scopes and the client secret update in place.
To set authentication in the Control Plane instead:
  1. Open the server in the Catalog.
  2. On the Configuration tab, under Authentication, choose an option for How does Formal authenticate to this server?
  3. For Linked accounts, choose an OAuth app. For Shared credentials, click Add credential.
  4. Click Save authentication.
Verify:
  1. Open the server in the Catalog. On its Configuration tab, you’ll see a Connector address, such as https://linear.gateway.<your-org>.connectors.joinformal.com/mcp. If the address is missing, the reason appears in its place.
  2. If you chose linked accounts or shared credentials, confirm that Formal is listed as the authorization server:

Connect MCP clients

Pick the URL based on where the client runs: Users can find the right URL and setup steps for over 40 clients on each server’s page in the Catalog. The steps account for whether their device runs the Endpoint. In the examples below, the server is named linear, and the Connector hostname is gateway.acme.connectors.joinformal.com.

Cloud apps and agents

Claude, ChatGPT, Dots, Cursor Cloud Agents, and Grok Bot call MCP servers from their vendor’s cloud, so they always use the Connector address. We recommend that an admin adds each server once for the whole team. Each member then only connects it and signs in to Formal. The Formal Endpoint doesn’t see these calls, even when it runs inside a cloud agent. The Add to Claude and Add to ChatGPT buttons appear under Add to your organization’s AI apps in the server’s Authentication section. You’ll see them once the server uses linked accounts or shared credentials and has a Connector address.
To add the server for your organization:
  1. In the Catalog, open the server and go to the Configuration tab.
  2. Under Add to your organization’s AI apps, click Add to Claude. Claude opens its organization connector settings with the server’s name and Connector address filled in.
  3. As a Claude Owner, confirm the connector.
Each member then connects:
  1. In Claude, open Settings → Connectors, find the server, and click Connect.
  2. Sign in to Formal and approve Claude on the Catalog consent screen.
  3. In a new conversation, enable the connector from the tools menu.
Verify: Ask the app or agent to list the server’s tools. Each call appears in Logs with your Formal identity. If you restrict inbound traffic to the Connector, allow the IP ranges that Anthropic, OpenAI, and Cursor publish for outbound connector traffic.

Claude Code

Use the server’s original URL. The Endpoint routes it through the gateway and adds your identity.
If the server uses linked accounts, link your account in the Catalog first.
Verify:

Codex

Use the server’s original URL:
If the server uses linked accounts, link your account in the Catalog first.
Verify:
Then ask Codex to list the server’s tools. Each call appears in Logs with your Formal identity.

Governance

Every request through the gateway carries a Formal identity, so you can control who uses each server and which tools they can call.

Restrict access and tools

  1. Go to Catalog and open the server.
  2. Open the Access Controls tab.
  3. Under Who can use this MCP?, choose Everyone, Specific users, or No one. With Specific users, add users and groups.
  4. Under Which tools can they use?, choose All tools or Specific tools. With Specific tools, select the allowed tools. Use the Read-only and Destructive filters to find tools by the hints each server publishes.
  5. Optionally, edit Message shown when access is denied.
  6. Click Save changes.
Formal saves these controls as a policy named MCP access controls: <server-name>. The Connector blocks requests from anyone outside the allowed users and groups. It also blocks tools/call requests for tools outside the list. Clients may still list those tools, but calls to them fail with the block message.
The Access Controls tab shows only the policy it created. Other policies can also restrict the server.

Write custom policies

For rules the tab doesn’t cover, write a policy on MCP traffic. Policies can read each call’s tool name and parameters. See MCP resources for an example and MCP policy inputs for every field.

Review usage

Tool calls appear in Logs with the user, server, and tool name. In the Catalog, a server’s Usage tab breaks down its requests by tool and by user.

Troubleshooting

Possible causes:
  • The Connector has no hostname, or no listener routes MCP
  • The Connector is in a different Space from the server
  • The server name isn’t a valid DNS label
Fix: Fix the cause listed in the Catalog, then reload the server.
Possible causes:
  • The certificate covers only the bare hostname, not *.<connector-hostname>
  • No wildcard DNS record exists
Fix: Re-run the dig and openssl checks in Deploy the Connector.
Cause: Grok Bot connects from Cursor’s cloud and can’t reach the Connector address.Fix: Expose the Connector hostname publicly over HTTPS on port 443. A private or VPN-only address doesn’t work.
Possible causes:
  • The client doesn’t support Client ID Metadata Documents
  • The client’s redirect URI isn’t in its metadata document
Fix: Pre-register the client with its exact redirect URIs, or route it through the Formal Endpoint.
Cause: The server doesn’t support CIMD, and Formal hasn’t registered an app with its provider.Fix: Switch OAuth app to Your OAuth app, and register an app with the provider.
Possible causes:
  • The server stopped supporting the OAuth app it was saved with
  • A pre-registered app is missing Formal’s redirect URI
Fix: Run the CIMD metadata check in Linked accounts. If the server doesn’t support CIMD, switch to Your OAuth app.

Next Steps

MCP servers

Browse Catalog templates and setup guides

MCP Resources

Write policies on MCP tool calls

OAuth and Linked Accounts

Use linked accounts on HTTP, gRPC, and LLM resources

Native Users

Manage shared credentials

Network Rules

Route Endpoint traffic to the Connector

Permissions

Control who can use the Catalog