Skip to main content
Forge MCP setup showing catalog, discovered and manual modes, transport, authentication, and gateway configuration

MCP Gateway setup

The MCP Gateway gives AI clients a governed connection to approved MCP servers. Forge authenticates the caller, resolves their identity and upstream credentials, removes disabled tools from discovery, applies Registry access rules and the normal Forge Content policy engine to every tool call, and records the complete decision path. Registry access rules and organization-authored Content policies use the same Forge policy engine. Registry rules establish who may use a server or tool; Content policies inspect the identity, MCP server, tool, arguments, session context, and result to control what happens inside an allowed call. Access policies can separately govern use of the client, MCP product, or route at connected endpoint and network enforcement surfaces.

​
Architecture

Each Registry item receives its own gateway URL:
The slug is permanent and is used by gateway URLs, policies, installations, and audit records.

​
Traffic entry

Forge can route supported MCP traffic through the gateway automatically, so organizations can govern existing connections without reconfiguring every AI client. Clients can also connect to the Forge gateway URL explicitly. In every case, Forge authenticates the caller and applies Registry and Content policies before connecting to the approved server. Automatic routing preserves the same access controls and audit trail as a directly configured client.

​
Server sources

Servers reach the Registry through three paths: Catalog entries distinguish vendor-operated remote servers from remote servers hosted inside a customer’s own SaaS or cloud instance. In every case, Forge publishes the governed gateway endpoint; the upstream server remains at its configured hosting location.

​
Add a server

Administrators can open Registry > Add MCP and choose Catalog, Discovered, or Manual. People who cannot manage the Registry see Request MCP instead. For a manual remote server:
  1. Enter the upstream MCP URL and select Streamable HTTP or SSE.
  2. Configure how Forge connects upstream. You can apply an optional connection template or edit the fields directly:
    • No authentication for a public server such as DeepWiki.
    • Shared bearer token or Shared custom header when Forge should send one organization credential.
    • Per-user OAuth when every person must connect their provider account.
    • Forward Forge identity when a trusted upstream accepts Forge identity headers or a signed identity assertion.
  3. Select Add MCP. Forge creates a server-wide allow rule for the administrator who added the server when their directory identity is linked.
  4. Forge opens the new server and attempts to synchronize tools, resources, resource templates, and prompts whenever the upstream is immediately usable.
  5. In Settings, use Save and test after changing the connection. A successful test also synchronizes capabilities.
MCPs selected from Discovered open the same review form before creation. Forge maps observed no-auth, token, and OAuth configurations to reachable settings. After the administrator confirms Add MCP, the server uses the same creator-access and setup destination as Catalog and Manual creation.
Upstream authentication does not control access to the hosted Forge URL. Interactive clients sign in to Forge so Registry policy and audit retain the caller’s identity. Service/API tokens are a separate automation option.
If automatic capability synchronization fails, the server and any successful OAuth connection remain intact. Open Capabilities to retry the sync. A catalog comparison distinguishes a server that has never synchronized, a failed sync, and live tools that differ from the vetted catalog baseline.

​
Transports

The client-facing Forge endpoint uses Streamable HTTP. Forge supports these upstream and compatibility paths: An active hosted gateway endpoint requires a remote Streamable HTTP or SSE upstream URL. A stdio server is represented in the Registry and delivered through the local bridge; Forge does not execute its process inside the hosted gateway.

​
Client authentication

Client authentication protects the Forge-facing endpoint independently of the credential used for the upstream server.

​
OAuth 2.1

Interactive MCP clients connect with Forge OAuth 2.1. Forge publishes OAuth authorization-server and protected-resource metadata for discovery, uses a dedicated MCP audience, and supports authorization-code exchange with PKCE, refresh, revocation, and dynamic client registration. The grant must include mcp:connect and any scopes required by the requested surface. The authenticated organization must match the organization in the gateway URL.
REST API access tokens use a different audience and cannot be reused as MCP OAuth tokens.

​
Service tokens

Non-interactive clients can send an approved service-account bearer token when automation tokens are enabled for the endpoint. The token must include mcp:connect, belong to the same organization and server installation, and carry the scopes required for the call. Use user OAuth for interactive assistants when individual attribution matters. Use service accounts for unattended apps, agents, and automation.

​
Upstream authentication

After local authorization succeeds, Forge resolves the credential presented to the upstream MCP server. For HTTP upstreams, static and OAuth access tokens can be placed in the Authorization header or a configured custom header. Environment-variable placement is reserved for local stdio execution and is not supported by the hosted HTTP proxy. Forge strips inbound X-Forge-* identity headers before constructing trusted identity forwarding. Clients therefore cannot supply or override the upstream Forge identity.

​
Secret handling

Organization credentials and OAuth client secrets are stored as managed Forge secret references. The gateway resolves them only after rate limits, capability state, Registry ACLs, and pre-tool policies permit the request. Secret values are not included in policy inputs or denial evidence.

​
OAuth configuration

Forge can discover an upstream server’s OAuth metadata or use explicit configuration. Forge supports PKCE with S256. A server can use a Forge-managed OAuth client when one is available, a customer-owned client, Dynamic Client Registration, or a Client ID Metadata Document. Callback rules restrict which redirect URIs can be used by MCP clients.

​
Client callback policy

Client callback rules apply to applications connecting to Forge. They do not configure the callback URL registered with an upstream provider. The callback policy is available for every hosted Registry MCP, including public upstreams with no upstream authentication, because interactive clients still authenticate to Forge.
  • With no client callback rules, Forge accepts valid HTTPS callbacks and permitted loopback callbacks.
  • Adding the first rule switches the organization to explicit-policy mode: callbacks must match an Allow rule, and Block rules take precedence.
  • The organization’s Forge callback is always trusted.
  • A rejected authorization response includes the exact callback URI. Copy that value into Settings > Client callback policy when the client is trusted; prefer an exact URL over a wildcard.
For example, a Cloudflare playground client may use a callback under https://playground.ai.cloudflare.com/. Configure that callback only when explicit rules already restrict the organization and the playground is an approved client. User-scoped OAuth connections are stored per Registry installation. Forge refreshes eligible grants and marks a connection for reconnection when its refresh path can no longer produce a valid access token.

​
Access controls

Registry access is blocked by default. An enabled rule must grant the actor access before Forge invokes a tool. Server-wide rules apply to every tool. Tool-scoped rules use the stable tool identities discovered from tools/list. Forge combines all matching Registry rules through normal Content-policy precedence; an allow does not bypass a stronger matching approval or block. Forge also uses this effective tool-level access when determining whether one identity can reach every exact tool named in a cross-server investigation occurrence. Registry rules are compiled into policy projections and remain visible with their source, revision, description, rationale, and scope. Organization-authored MCP ACLs can coexist with Registry-owned rules.

​
Tool visibility

Forge removes tools disabled in the Registry from tools/list. Registry ACLs and Content policies are then enforced again on every tools/call; receiving a tool definition from the upstream server does not grant permission to invoke it. Naming a disabled or unauthorized tool directly does not bypass authorization.

​
Content policies

MCP Gateway calls participate in the same Content policy engine used across other Forge enforcement surfaces.

​
Pre-tool

Before tools/call reaches the upstream server, policies can evaluate:
  • User, group, and service-account identity.
  • MCP server and stable tool identity.
  • Tool name and structured arguments.
  • Agent, product, and session context available to the gateway.
Compatible actions include allow, block, review, approval, nudge, and input redaction. Approval grants are bound to the matching policy revision and subject. Redaction rewrites the structured tool arguments before Forge resolves the upstream credential and sends the request.

​
Post-tool

After a successful upstream call, policies can inspect the tool result before it returns to the client. Compatible actions can:
  • Block the result.
  • Redact the complete result or selected structured paths.
  • Filter objects from a structured collection.
  • Flag the event for review.
  • Attach policy guidance for the next supported model step.
See Policies, Actions, and Redaction for the complete policy schema and action constraints.

​
Request limits

Gateway endpoints can enforce request limits within a configurable window. Limits can apply independently to: Individual tools can override the endpoint’s default tool and per-user tool limits. Forge returns 429 and records the limiting scope, configured limit, observed count, and window when a request is rejected.

​
Tool inventory

Forge refreshes the server’s MCP surfaces and records each tool’s name, description, input schema, content digest, discovery state, and first and last observation. Changes are separated into added, changed, unchanged, and removed tools. Tool definitions can be evaluated for:
  • Read, write, administrative, and destructive capability.
  • Package and source provenance.
  • Schema or description changes.
  • Deterministic and semantic risk findings.
Administrators can disable an individual tool without removing the whole server. Disabled tools are removed from discovery and rejected at invocation.

​
Evaluation order

For each tools/call, Forge evaluates:
  1. The client credential, organization, mcp:connect capability, endpoint state, and server binding.
  2. The active transport, session, and configured request limits.
  3. Whether the tool is disabled and whether a stable identity is available for tool-scoped rules.
  4. Registry-owned and organization-authored MCP access rules.
  5. Pre-tool Content policies and any required approval grant.
  6. Upstream credential or trusted identity forwarding.
  7. The upstream MCP request.
  8. Post-tool Content policies and result transformations.
  9. Session, governance decision, policy hit, latency, and audit persistence.
The upstream credential is not resolved and the upstream server is not called when a local gate denies the request.

​
Sessions

MCP Gateway sessions preserve actor and endpoint boundaries. A session cannot be resumed by another actor or used against a different Registry server. Streamable HTTP clients can create, resume, and delete sessions through the gateway endpoint. Each call records the actor, server, tool, outcome, policy or access-rule evidence, HTTP status, latency, and session relationship. Forge distinguishes allowed, denied, approval-required, rate-limited, authentication, credential, transport, configuration, and upstream-error outcomes. Applications using both Forge LLM Gateway and MCP Gateway can attach the exact parent model tool-call identifiers. This correlation links the MCP invocation to its originating model session but never grants access or changes a policy decision. See MCP for client configuration, OAuth connection examples, local bridge commands, and correlation headers.