> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Forge MCP server

> Hosted and stdio MCP connection modes, tool discovery, calls, confirmations, paging, resources, and prompts.

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](https://docs.gloo.com/forge/quickstart/mcp-host.md) has copyable host configuration for each supported mode.

| Transport | Credential | Supported host shape |
| - | - | - |
| Hosted Streamable HTTP | Interactive OAuth | Claude Code and VS Code connect without an embedded secret |
| Hosted Streamable HTTP | Personal key | Bearer header supplied from a secret environment/input |
| Local stdio package | External App | Server mints and refreshes client-credentials tokens |
| Local stdio package | Personal key | `FORGE_API_KEY` bearer |

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](https://docs.gloo.com/forge/quickstart/mcp-host.md).

### 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](https://docs.gloo.com/forge/quickstart/mcp-host.md). 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](https://docs.gloo.com/forge/reference/idempotency.md).

### 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](https://docs.gloo.com/forge/knowledge/external-sources.md) for current configuration and terminology.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.