> ## Documentation Index > Fetch the complete documentation index at: https://docs.forge.ai/llms.txt > Use this file to discover all available pages before exploring further. # MCP > Connect MCP clients to Forge or route approved upstream MCP servers through the Forge MCP Gateway. 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: ```text theme={"system"} https://mcp.forge.ai/mcp ``` An unauthenticated request receives a `WWW-Authenticate` challenge with the protected-resource metadata URL. The canonical metadata document is: ```text theme={"system"} 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. ```http theme={"system"} Authorization: Bearer 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. ```json theme={"system"} { "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: ```http theme={"system"} 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](/developer/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: ```text theme={"system"} 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: ```bash theme={"system"} 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: ```bash theme={"system"} 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: ```bash theme={"system"} 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: ```bash theme={"system"} 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: ```bash theme={"system"} forge mcp tokens github ``` Rotate a token before it expires or whenever its local copy may have been exposed: ```bash theme={"system"} 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: ```bash theme={"system"} 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: ```bash theme={"system"} 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](/developer/api). ## Authorization Forge reevaluates every `tools/list` and `tools/call`. A tool is callable only when all applicable gates pass: 1. MCP is enabled for the organization. 2. The actor has the `mcp.connect` capability and `mcp:connect` scope. 3. The session selected the tool's toolset. 4. The capability supports MCP and the actor has its required permission and scopes. 5. Organization read-only and destructive-tool settings allow the capability. 6. The call arguments satisfy the advertised JSON Schema. 7. 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: ```json theme={"system"} { "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 ```bash theme={"system"} forge mcp sessions forge mcp revoke-session \ --session session_123 \ --reason "Retired workstation in INC-456" \ --idempotency-key "inc-456-session-123-revoke" \ --confirm ``` Review Forge MCP tools and their runtime metadata. Review MCP registry and session commands. Understand policy and response controls for upstream MCP traffic. Review the MCP request and approval model.