Skip to main content
Forge MCP lets an MCP host discover and perform Forge tasks. It exposes a bounded default tool surface, searchable HTTP operations, resources, resource templates, and prompts. It does not list every API operation as a dedicated tool. Release snapshot: 14.3.0. It registers 77 tools, 8 resources and 13 resource templates across its groups. A connection lists only its selected and credential-visible subset. The source tree may contain changes for a later release.

Connection modes

Choose hosted HTTP for an interactive host, or the local stdio package when the server must manage External App token refresh. The MCP quickstart has copyable host configuration for each supported mode. The hosted endpoint does not accept External App client credentials because it cannot refresh that client’s token. Use local stdio for an unattended External App. See MCP quickstart.

Hosted endpoint

Connect a Streamable HTTP host to https://mcp.forge.gloo.com/mcp. The hosted endpoint is POST-only; a GET request is not a sign-in or health probe. The host must support the selected credential mode.

Interactive sign-in

An OAuth-capable host can start a person sign-in without embedding an External App secret. Complete the browser authorization, then open Settings → Personal keys → Host sign-ins in Console. A new sign-in has no scopes. Grant the scopes needed for your task and reconnect the host or refresh its tool list. The scopes narrow your current roles; they do not grant new authority. If the host cannot perform interactive OAuth, use its supported bearer-header configuration with a Personal key.

Connect a remote host

Use the hosted URL, choose a credential mode supported by that host, and follow the host configuration examples. Confirm the connection by inspecting the current actor and the returned tool list. A connected transport alone does not prove resource authority.

External App client credentials

Use the local stdio package for an unattended External App. It reads the configured client id and secret, mints a token, and refreshes it before expiry. The hosted endpoint cannot perform this client-secret refresh on a remote host’s behalf. Keep credentials in the host’s secret environment, as shown in the quickstart.

Discover before calling

The start listing contains common tools and stays intentionally bounded. The retired extended toolset does not restore an exhaustive list.
  1. Use forge_find to locate a named workflow, procedure, agent, tool, or knowledge record.
  2. Use forge_search_operations for wider API capability discovery.
  3. Use forge_describe_operation to read the operation’s method, input, permission, credential, and safety metadata.
  4. Call a read with forge_call_read_operation.
  5. Call a write with forge_call_operation and honor host confirmation.
forge_call_read_operation accepts GET operations and the cataloged knowledge POST reads. Other POST operations remain writes even if their name sounds observational. Pass an id exactly as a result returned it, never a name or a guessed id. Each tool that takes an id shows its form, either in the tool’s example or in the id input’s own description. The first three results of forge_search_operations also carry inputSchema, the operation’s input as forge_describe_operation returns it, with any component schemas it references. A new operation can then be called in two calls: search, then call. A schema over 2 KB is left out and the result says inputSchemaOmitted: true; describe that operation before calling it.

Credential-filtered tool list

The connected credential’s authority and selected tool group affect tools/list. A tool absent from that list is not restored by guessing its name. Wider operation discovery still requires the operation’s own permission and credential checks.

Common task tools

Dedicated tools cover high-frequency jobs such as finding resources, listing and inspecting runs, triaging a run, explaining a denial, handling a human task, and running a workflow to a bounded wait. forge_ask_workflow_architect starts or continues a Workflow Architect conversation and can return a changed draft or a plan waiting for a person. It requires a Personal key and workflow read and write authority; sending a message is confirmed because it cannot be recalled. Use tools/list on the active connection as the source of truth for exact names and schemas. The start group supports discovery and common operating tasks; it is not a complete mirror of the HTTP catalog.

Current actor

forge_get_current_actor identifies the connected principal and its available authority. Use it before troubleshooting a denial or assuming that the host is acting as a different person or app.

Operation tools

The search, describe, read-call, and write-call tools provide access to the wider operation catalog. API requests use /api/v3; use the input schema returned by search or describe for each operation’s stable argument names. Inspect the operation’s credential, permission, input, and confirmation metadata before calling it. Discovery does not grant access.

Knowledge job

Knowledge tools, including forge_search_knowledge, return evidence the caller may read. A permission denial is different from an empty search. Choose the task tools exposed by the connection and follow their current schemas.

Approvals job

forge_list_approvals reads approval work visible to the current connection. An approval resolution still checks the person’s eligibility and the specific release policy. Listing an item is not authority to resolve it.

Confirmations and refusals

forge_call_operation confirms operations whose route declares an irreversible effect, including data loss, delivery, authority, or going live. Reassignment and other dedicated tools can also require confirmation. Never bypass a confirmation by selecting a lower-level caller. How the confirmation reaches a person depends on the host and the credential:
  • A host that declares form elicitation (and not URL elicitation) asks its user in its own UI. The answer comes from the host, never from the model.
  • Otherwise Forge records that exact call and refuses it with confirmation_required, carrying confirmationUrl, a Forge Console page, plus confirmationId, expiresAt and status. A host that declares URL elicitation opens the link for its user and waits for the decision. The credential’s owner approves or denies the one call on that page, signed in to the Console; the identical retried call then runs, once. The agent receives no token, and nothing it holds can approve. The hosted endpoint always answers with the link. A confirmation expires after ten minutes.
  • An External App runs a destructive call once a person with apps:manage preauthorized it on the app’s Console page; Forge’s audit of the call names that person. Until then, and for a platform key, the refusal is confirmation_required with a deprecated confirmationToken that the agent sends back only after the user agrees. That path is being retired; a sunset date will be announced.
Every listed tool that can write to systems outside Forge is confirmed too, because cancelling a run does not undo what its steps wrote: forge_dispatch_workflow, forge_run_workflow_and_wait when it starts a run (following a runId alone is not confirmed), forge_restart_run, forge_start_run_analysis (its agent may call the external tools granted to it), and forge_ask_workflow_architect when it sends a message. forge_call_operation confirms the operations that start a run by the same rules: dispatchWorkflow, restartRun, startRunAnalysis, testRunWorkflowDraft and launchWorkflowDebugAttempt. The confirmation names each argument that changes the run: its version, factory, customer, inputs, callback URL and, for a restart, a raised cap. A refusal uses { error: { code, message, ... }, meta: { requestId } }. When Forge can name a safe next call, error.continuation contains its tool and arguments. A continuation is guidance, not proof that the next call will be authorized. Every refusal’s text starts the same way: Forge API error (<status> <code>): when Forge answered, and Forge MCP error (<code>): when the server refused the call itself. An invalid_input refusal lists each failing field in error.details, with its path, message and code, plus the values the field accepts as allowed when there is a fixed set. A resource_missing (or older not_found) refusal names a listed forge_list_… tool for the record’s kind when the connection lists one, and the list operation otherwise. A permission_denied or forbidden refusal that names a decisionId passes it to forge_explain_denial in its next step. The credential it refused reads that decision as its own (GET /api/v3/me/denials/{decisionId}), with no permission. Any other decision is read from the recorded evidence, which needs audit:read, grants:read and policies:read. When neither read answers, the explanation still answers, with decision: null. Every tool input declares its bounds in tools/list: a minimum and maximum on each number, a maxLength on each free-text string and a maxItems on each list. A value outside them is refused with invalid_input before any request is sent; a limit above its maximum is refused, not lowered to it.

Paging and large results

Follow meta.nextCursor while meta.hasMore is true. Every tool’s text content is at most 16 KiB: an answer over that keeps the first items of its long lists, says how many were left out, and ends with a [Truncated: …] note, while structuredContent retains the whole answer. If the text says rows were omitted, repeat with the same cursor and a smaller limit before advancing to the page’s nextCursor. Most list tools take fields, a list of row keys to keep. For example, forge_list_runs {"fields":["status","error"]} returns each row with only id, status and error. Every projected row keeps its id when it has one. The projection applies to the text content only: structuredContent still carries whole rows. An unknown key is refused as invalid_input, and error.details[] names each unknown key and lists the keys a row has in allowed. The tools that take fields are forge_list_agents, forge_list_approvals, forge_list_knowledge_cases, forge_list_knowledge_reviews, forge_list_knowledge_scopes, forge_list_my_grants, forge_list_procedures, forge_list_run_approvals, forge_list_run_artifacts, forge_list_run_events, forge_list_runs, forge_list_skills, forge_list_tools, forge_list_workflow_templates and forge_list_workflows. Large run-report pages are returned as a summary plus a resource_link; read the linked forge://runs/.../report...md resource instead of expecting the Markdown inline. When a text answer would pass 16 KiB, its text is shortened to a structural summary that ends with a [Truncated: ...] note. structuredContent still carries the whole answer, and the result also does one of these:
  • A list or search says how to page in that note. Rows left out of the text come back with the same cursor and a smaller limit. The cursor the answer returned continues after the whole page, past those rows.
  • A single record or read links its whole answer with a resource_link. A tool with a resource for the same read links that resource, such as a workflow, a run’s timeline, a knowledge record or case, or the budgets. Any other read-only tool links forge://tools/{toolName}/result?input=..., which runs that call again with your credential and returns its whole structuredContent. It refuses a tool that is not read-only. forge_run_workflow_and_wait starts a run, so it links the run’s forge_get_run result, and its outcome through forge_call_read_operation. A link is only one your connection can read, under its job, tool group and permission selection. A tool your connection does not reach is read through forge_call_read_operation when its one operation is reachable; otherwise there is no link, only the note.
  • Writes answer a small fixed acknowledgement and never reach the cap. forge_call_operation, forge_handle_human_task, forge_ask_workflow_architect and forge_ask_knowledge keep only the summary and its note.

Resources and prompts

Resources

Resources provide bounded views such as current actor, agents, apps, runs, OpenAPI, and paged run reports, depending on the connection’s authority. Inspect resources/list and resources/templates/list. Read linked report resources when a tool returns a resource_link. Some reads link the resources they summarize after their text: forge_get_run links the run’s report (forge://runs/{runId}/report.md) and timeline (forge://runs/{runId}/timeline), and forge_get_workflow links the workflow’s definition (forge://workflows/{workflowId}) by the id it returned, even when it was called with a name. Each link is to a template the same connection lists, and reading it uses the connection’s own credential.

Subscriptions and list changes

The local stdio package is one session, so it can notify its host:
  • Resource subscriptions. It declares resources.subscribe. A host can subscribe to up to 20 resource URIs. Each subscribed URI is read again every 15 seconds with the connection’s own credential, and notifications/resources/updated arrives when its contents change.
  • Tool and prompt list changes. It declares tools.listChanged and prompts.listChanged. Every minute it reads the credential’s permissions again. It sends notifications/tools/list_changed when a grant changes which tools it lists, and notifications/prompts/list_changed when that changes which prompts it lists (a prompt is listed only with every tool it names). forge_find searches the kinds the credential can read as of that re-read.
The hosted endpoint builds a server per request, so it keeps no session to notify. It declares listChanged: false and no resources.subscribe. A hosted host reads tools/list and resources again when it needs them.

Prompts

Prompts orchestrate existing tools; they do not grant permission or bypass confirmation. Inspect prompts/list and use the connected prompt’s declared arguments. Workflow execution prompts retain the workflow’s launch and dispatch checks.

Completions

Supported prompt and resource references can offer argument completions. Completion suggestions help form a valid call; they do not prove that the subsequent read or write is authorized. Use the connected server’s reference and argument schemas.

Recovery

  • Hosted OAuth 401: sign in again; a revoked sign-in may need removal in Personal keys first.
  • Personal-key 401: replace or reauthorize the key.
  • External App 401: the local server re-mints before expiry and may repeat a read once, never a write. Check client state if minting returns invalid_client.
  • 403: inspect the required permission, key scopes, roles, resource scope, and whether a person is required.
The package contract and release notes are the authority for version-specific tool schemas.

Rate limits and retry hints

A rate-limited response can carry Retry-After. The client can wait and retry a bounded read according to its contract; writes are not automatically repeated. If refusal evidence includes a retry delay, honor it rather than immediately issuing another call.

Unknown outcomes

A timeout or disconnected host does not prove that a write failed. Read the resulting run, task, or effect evidence before another attempt. Reuse the operation’s idempotency contract where supported; never generate a fresh write merely to discover what happened to the first one. See Idempotency.

Usage headers

During a tool call, the MCP client names the tool with X-Forge-Mcp-Tool and, when valid and available, the host with X-Forge-Mcp-Client. These are usage attribution, not authorization. Credential and governance checks remain authoritative.

Versioning and deprecation

Use the connected server’s tool schemas and the package release notes for the version you run. Retired names and the old extended toolset are not compatibility switches. For wider capability access, use operation discovery and description rather than retaining a removed dedicated tool name.

Synchronized-source naming

Synchronized source operations use synchronized-sources in their compatibility HTTP paths and the synchronized_knowledge capability domain. For example, discover createSynchronizedSource, describe its schema, then invoke it through forge_call_operation. The old forge_*_knowledge_source* aliases were retired after their support interval; selecting a retired toolset does not restore them. See Knowledge sources for current configuration and terminology.