Skip to main content
Choose the connection mode by actor. A person should normally use hosted interactive OAuth. An unattended application should run the stdio package with its own External App credentials.

Hosted OAuth for a person

Hosts that support Streamable HTTP and OAuth discovery can connect without storing a Forge secret in configuration:
Complete sign-in in the host, then open Settings → Personal keys → Host sign-ins in Console. A fresh sign-in starts with no scopes. Grant the read scopes needed by your task, such as 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:
Do not commit the environment value. A Personal key acts as its owner.

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:
Install/package registry access depends on how your organization distributes the package. Keep the client secret outside a committed config when the host supports environment expansion.

Verify the connection

  1. List tools and confirm forge_get_current_actor is available.
  2. Call it and verify the actor kind and effective operation detail match the credential you chose.
  3. Use forge_find for a known workflow, procedure, agent, tool, or knowledge record.
  4. Search and describe an operation before calling it.
  5. 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 lists start: 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 jobs to the URL, for example https://mcp.forge.gloo.com/mcp?jobs=start,approvals, or send the X-Forge-Mcp-Jobs header 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’s env.
Jobs decide which tools are listed, not what the credential may do. A tool outside the selected jobs answers 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

  • 401 with hosted OAuth: sign in again from the host.
  • 401 with a key: replace or reauthorize it.
  • invalid_client from 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: MCP server reference.

Next steps