> ## 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.

# Connect an MCP host

> Connect a supported host to Forge through hosted OAuth, a Personal key, or local External App credentials.

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:

```json theme={null}
{
  "mcpServers": {
    "forge": {
      "type": "http",
      "url": "https://mcp.forge.gloo.com/mcp"
    }
  }
}
```

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](https://docs.gloo.com/forge/console/settings/personal-keys.md#host-sign-ins).

## Hosted access with a Personal key

For a host that sends explicit headers, keep the key in a secret environment variable:

```json theme={null}
{
  "mcpServers": {
    "forge": {
      "type": "http",
      "url": "https://mcp.forge.gloo.com/mcp",
      "headers": {
        "Authorization": "Bearer ${FORGE_MCP_KEY}"
      }
    }
  }
}
```

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:

```json theme={null}
{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["@tangogroup/forge-mcp"],
      "env": {
        "FORGE_API_URL": "https://api.forge.gloo.com",
        "FORGE_CLIENT_ID": "<client-id>",
        "FORGE_CLIENT_SECRET": "<secret>",
        "FORGE_TOKEN_SCOPE": "workflows:read workflows:use runs:read"
      }
    }
  }
}
```

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:

| Job | Adds tools for |
| - | - |
| `start` | The default set above. |
| `access` | Your own authority and grants, permission explanations, the permission catalog, stop state and budget status. |
| `work` | Your work queue and attention items. |
| `approvals` | Approvals and human tasks: read, act, complete, reassign, and their input and output files. |
| `find` | Workflows, workflow templates, agents, procedures, tools and skills by name or ID, and a docs search. |
| `run` | Dispatching a workflow, readiness checks, and a run's outcome, events, artifacts, cancel and restart. |
| `explain` | A run's timeline, steps, debug bundle, provenance, citations and analysis. |
| `knowledge` | Knowledge search and questions, scopes, records, cases and the review queue. |

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

## Next steps

* [MCP server reference](https://docs.gloo.com/forge/reference/mcp-server.md): every job and tool a connection can list.
* [Personal keys](https://docs.gloo.com/forge/console/settings/personal-keys.md): manage the key or host sign-in a connection uses.
* [Choose a Forge interface](https://docs.gloo.com/forge/get-started/choose-an-interface.md): when to use MCP, the Console or the HTTP API.


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