Hosted OAuth for a person
Hosts that support Streamable HTTP and OAuth discovery can connect without storing a Forge secret in configuration:workflows:read, procedures:read, or agents:read, then reconnect the host or refresh its tool
list before verifying the connection. These scopes narrow the signed-in person’s existing roles;
they do not grant new authority. See Host sign-ins.
Hosted access with a Personal key
For a host that sends explicit headers, keep the key in a secret environment variable:Local stdio for an External App
Use this mode for unattended or shared software because the local server can mint and refresh the app’s short-lived token:Verify the connection
- List tools and confirm
forge_get_current_actoris available. - Call it and verify the actor kind and effective operation detail match the credential you chose.
- Use
forge_findfor a known workflow, procedure, agent, tool, or knowledge record. - Search and describe an operation before calling it.
- Run only a safe read during setup.
Understand the tool model
The default listing is intentionally bounded;extended is retired. Use
forge_search_operations and forge_describe_operation for the wider API catalog, then
forge_call_read_operation for a read or forge_call_operation for a write. Writes and declared
irreversible effects can require host confirmation.
For workflow authoring, forge_ask_workflow_architect can propose or change a draft and may return
a plan waiting for a person. It accepts only a Personal key because the conversation acts as a
person.
Choose the jobs a connection lists
A connection lists the tools of the jobs it selects. With none selected it listsstart: the
current actor, the operation tools (forge_search_operations, forge_describe_operation,
forge_call_read_operation, forge_call_operation), and the composite tools for the common tasks.
Select more jobs when a host should see dedicated tools for one area:
Name the jobs as a comma-separated list. A list replaces the default, so include
start to keep
it; unknown names are ignored.
- Hosted endpoint: add
jobsto the URL, for examplehttps://mcp.forge.gloo.com/mcp?jobs=start,approvals, or send theX-Forge-Mcp-Jobsheader with the same list. When both are present, the connection lists the jobs of both. - Local stdio server: set
FORGE_MCP_JOBS, for example"FORGE_MCP_JOBS": "start,run,explain"in the server’senv.
tool_not_listed; its operation stays reachable through forge_call_operation or
forge_call_read_operation wherever the deployment’s tool groups allow it. Reconnect the host or refresh its tool list after changing the
selection.
Troubleshoot
401with hosted OAuth: sign in again from the host.401with a key: replace or reauthorize it.invalid_clientfrom stdio: verify app activation, client id, and secret.403: check the named permission, key/token scopes, role grants, resource scope, and whether the operation requires a person.tool_not_listed: the current connection does not expose that tool; inspect the listing and use operation discovery where appropriate.
Next steps
- MCP server reference: every job and tool a connection can list.
- Personal keys: manage the key or host sign-in a connection uses.
- Choose a Forge interface: when to use MCP, the Console or the HTTP API.

