MCP - Forge

Forge exposes two distinct MCP surfaces:

Surface	Endpoint	Purpose
Forge MCP	`https://mcp.forge.ai/mcp`	Call Forge inventory, investigation, policy, governance, compliance, fleet, registry, and administration tools.
MCP Gateway	Returned by a registry installation	Call an approved upstream MCP server through Forge policy, identity, session, and audit controls.

Both surfaces use Streamable HTTP. Forge MCP currently negotiates MCP protocol version 2025-06-18.

Forge MCP

Discovery

Add this remote server URL to a Streamable HTTP client:

https://mcp.forge.ai/mcp

An unauthenticated request receives a WWW-Authenticate challenge with the protected-resource metadata URL. The canonical metadata document is:

https://mcp.forge.ai/.well-known/oauth-protected-resource/mcp

It declares the MCP resource, authorization server, supported scopes, and header-based bearer authentication. OAuth clients should discover these values rather than hard-code the authorization server.

Authentication

Interactive clients use OAuth 2.1 for the MCP resource audience. The resulting grant preserves the user identity, organization, role, scopes, and client identity. REST API access tokens use a different audience and are rejected. Non-interactive clients that support custom authorization headers can use a Forge service-account bearer token with mcp:connect and the scopes required by the selected tools.

Authorization: Bearer <mcp-access-token>
Accept: application/json, text/event-stream
Content-Type: application/json

Protocol methods

Method	Forge behavior
`initialize`	Creates or resumes a Forge MCP session and returns the negotiated protocol version, server information, and tool capability.
`notifications/initialized`	Accepted without a response body.
`ping`	Verifies authorization and creates or touches the session.
`tools/list`	Returns only tools authorized for the actor, scopes, organization settings, and selected toolsets.
`tools/call`	Validates arguments against the advertised JSON Schema, rechecks authorization, executes the underlying Forge capability, and records the decision.
`notifications/cancelled`	Accepted without a response body.

Other methods return JSON-RPC -32601. The initialize, ping, and tool responses include MCP-Session-Id. Send that header on subsequent requests. A revoked session cannot be silently recreated with the same identifier.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

Tool selection

Forge defaults to the metadata and default-read toolsets. A client can request an explicit comma-separated selection before session creation:

X-Forge-MCP-Toolsets: metadata,default-read,inventory-read,policy-read

The session retains that selection. Toolsets select a surface; they do not grant authorization. tools/list still removes any tool whose capability is denied by role, scope, read-only mode, or destructive-tool policy. See Tool Reference for tool names, response envelopes, and authorization metadata.

Connect an approved server

You can connect a Streamable HTTP client directly with the hosted endpoint shown on the Registry server:

https://mcp.forge.ai/organizations/{organizationId}/servers/{serverSlug}/mcp

Add that URL to the MCP client. Interactive clients should follow Forge OAuth discovery and open Forge sign-in automatically. If the upstream also uses per-user OAuth, Forge asks the user to connect that provider account as a separate step. A server configured with No upstream authentication still uses Forge sign-in at the hosted endpoint; it simply sends no credential from Forge to the upstream server. For unattended clients, enable service/API tokens on the Registry server and use an MCP-audience service token. Do not substitute a REST API token. If the client reports that its redirect URI is not allowed, copy the exact redirect_uri from the authorization error. An administrator can add it under Registry > server > Settings > Client callback policy. Organizations with no callback rules accept valid callbacks by default; once any rule exists, an Allow rule must match and Block rules take precedence. Forge CLI installs an approved registry server into Claude Code or Codex, creates a gateway credential for that client installation, and records the installation in the active Forge profile:

forge auth login
forge mcp list --status approved
forge mcp show github
forge mcp install github --client claude-code
forge mcp status github --client claude-code

For Codex:

forge mcp install github --client codex

Pass --config PATH when the client configuration is not in its default location. The CLI modifies only the selected server entry and preserves unrelated client configuration. On supported systems, its gateway token is stored in the operating-system keychain rather than in the client configuration. forge mcp run SERVER starts a local stdio bridge for clients that cannot connect to the remote Streamable HTTP endpoint.

Two authentication boundaries

A registry definition determines whether the upstream server uses an organization credential, a per-user credential, or OAuth. Gateway and upstream credentials are separate: the first authenticates the client to Forge; the second authenticates Forge to the upstream server.

Credential	Used between	Managed by
Forge gateway token	MCP client and Forge	Issued per user installation and stored locally by the Forge CLI
Upstream credential	Forge and the upstream server	Configured on the Registry item or authorized by the user through OAuth 2.1

Rotating or revoking a gateway token does not change the upstream server credential. Disconnecting upstream OAuth does not make a revoked gateway token valid again. Discover and register an OAuth-capable upstream:

forge mcp oauth-discover --url "https://provider.example.com/mcp"

forge mcp oauth-register-upstream provider-slug \
  --client-name "Forge MCP Gateway" \
  --scopes "scope-a,scope-b"

The registration command supports --redirect-uri, --no-discovery, and --no-persist for providers whose registration lifecycle requires explicit control.

Manage gateway tokens

Use a separate gateway token for each client installation. This keeps access independently attributable and lets you rotate or revoke one client without interrupting the others.

Issue and store

forge mcp install handles token issuance and secure local storage automatically. To create a token for another supported client workflow:

forge mcp create-token github \
  --name "Claude Desktop on Amelia's Mac" \
  --expires-days 90

The plaintext secret is returned only when the token is issued. Forge stores only its hash, so copy the secret into the intended client’s secure credential store before closing the output. Token lists and later API responses contain only non-secret metadata. Gateway tokens expire after 90 days by default. You can select a lifetime from 1 to 365 days when issuing or rotating one.

Inspect, rotate, and revoke

List a server’s tokens to review their IDs, client names, status, expiry, and last-used time:

forge mcp tokens github

Rotate a token before it expires or whenever its local copy may have been exposed:

forge mcp rotate-token github \
  --token mgtok_123 \
  --expires-days 90 \
  --confirm

Rotation revokes the previous token immediately and returns the replacement secret once. Update the client credential before its next connection. Revoke a token that is no longer needed:

forge mcp revoke-token github \
  --token mgtok_123 \
  --confirm

Revocation takes effect at the Forge gateway and does not reveal or modify the upstream credential.

Uninstall

Remove a Registry server from a local client with:

forge mcp uninstall github --client claude-code

Uninstall removes only that server’s local client configuration and revokes the gateway token associated with that installation. It does not remove the Registry item or revoke a separately managed upstream OAuth grant or organization credential. For direct automation, the same list, issue, rotate, and revoke operations are available through the Forge REST API.

Authorization

Forge reevaluates every tools/list and tools/call. A tool is callable only when all applicable gates pass:

MCP is enabled for the organization.
The actor has the mcp.connect capability and mcp:connect scope.
The session selected the tool’s toolset.
The capability supports MCP and the actor has its required permission and scopes.
Organization read-only and destructive-tool settings allow the capability.
The call arguments satisfy the advertised JSON Schema.
Guarded mutations contain the required reason, idempotency key, dry-run, and confirmation inputs.

Arguments cannot target an organization other than the authenticated actor’s organization.

Results and errors

Successful tools/call results contain both MCP text content and a structured result:

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"items\": []\n}"
    }
  ],
  "structuredContent": {
    "tool": "forge_inventory_search",
    "capabilityId": "inventory.read",
    "status": 200,
    "result": {
      "items": []
    }
  },
  "isError": false
}

JSON-RPC code	Meaning
`-32700`	Invalid JSON-RPC or request exceeds the accepted body size.
`-32601`	Unsupported MCP method.
`-32602`	Unknown tool, malformed parameters, or arguments that fail the tool schema.
`-32603`	Forge could not execute the tool or create the session.
`-32001`	Authentication is required.
`-32003`	Authorization, selected toolset, organization setting, or session state denied the call.

When an underlying Forge API operation returns a non-2xx result, MCP returns a tool result with isError: true and a bounded Forge error payload. It does not convert that domain error into a JSON-RPC transport error. Tool output is bounded. Large responses indicate truncation or expose pagination fields; continue with the returned cursor or offset rather than assuming the first result is exhaustive.

Correlation

Applications using both the Forge LLM Gateway and MCP Gateway can bind a tools/call request to the LLM tool call that caused it:

Header	Required	Value
`X-Forge-Parent-Event-Id`	Yes	Exact `tool.*` event ID from the Forge session timeline.
`X-Forge-Parent-Tool-Call-Id`	Yes	Provider tool-call ID from the LLM response.
`X-Forge-Parent-Session-Id`	No	Forge LLM session ID.
`X-Forge-Parent-Model-Invocation-Id`	No	Forge model invocation ID.
`X-Forge-Parent-Policy-Decision-Id`	No	Forge policy decision ID.

Forge accepts the binding only when the parent event exists in the same organization and is a tool event. Invalid correlation is ignored; it never grants access, changes a policy decision, or reaches the upstream MCP server.

Sessions

forge mcp sessions

forge mcp revoke-session \
  --session session_123 \
  --reason "Retired workstation in INC-456" \
  --idempotency-key "inc-456-session-123-revoke" \
  --confirm

Tool Reference

Review Forge MCP tools and their runtime metadata.

Commands

Review MCP registry and session commands.

MCP Gateway

Understand policy and response controls for upstream MCP traffic.

MCP Requests

Review the MCP request and approval model.

​Forge MCP

​Discovery

​Authentication

​Protocol methods

​Tool selection

​Connect an approved server

​Two authentication boundaries

​Manage gateway tokens

​Issue and store

​Inspect, rotate, and revoke

​Uninstall

​Authorization

​Results and errors

​Correlation

​Sessions