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 tohttps://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
Thestart listing contains common tools and stays intentionally bounded. The retired extended
toolset does not restore an exhaustive list.
- Use
forge_findto locate a named workflow, procedure, agent, tool, or knowledge record. - Use
forge_search_operationsfor wider API capability discovery. - Use
forge_describe_operationto read the operation’s method, input, permission, credential, and safety metadata. - Call a read with
forge_call_read_operation. - Call a write with
forge_call_operationand 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 affecttools/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, includingforge_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, carryingconfirmationUrl, a Forge Console page, plusconfirmationId,expiresAtandstatus. 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:managepreauthorized 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 isconfirmation_requiredwith a deprecatedconfirmationTokenthat the agent sends back only after the user agrees. That path is being retired; a sunset date will be announced.
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
Followmeta.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 linksforge://tools/{toolName}/result?input=..., which runs that call again with your credential and returns its wholestructuredContent. It refuses a tool that is not read-only.forge_run_workflow_and_waitstarts a run, so it links the run’sforge_get_runresult, and its outcome throughforge_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 throughforge_call_read_operationwhen 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_architectandforge_ask_knowledgekeep 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. Inspectresources/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, andnotifications/resources/updatedarrives when its contents change. - Tool and prompt list changes. It declares
tools.listChangedandprompts.listChanged. Every minute it reads the credential’s permissions again. It sendsnotifications/tools/list_changedwhen a grant changes which tools it lists, andnotifications/prompts/list_changedwhen that changes which prompts it lists (a prompt is listed only with every tool it names).forge_findsearches the kinds the credential can read as of that re-read.
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. Inspectprompts/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 returnsinvalid_client. 403: inspect the required permission, key scopes, roles, resource scope, and whether a person is required.
Rate limits and retry hints
A rate-limited response can carryRetry-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 withX-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 oldextended 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 usesynchronized-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.
