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

> Connect an agent-capable host using the access and setup options available to your account.

Use **Settings → Connect an agent** (`/settings/connect-agent`) to connect your own MCP host to Forge. The page provides the endpoint for your deployment and host-specific configuration. The connection acts through your credential's authority; adding a server does not grant permissions.

![Connect an agent (light)](https://mintcdn.com/gloo-b243725a/Ndtg9NEpwGc2OULA/forge/images/console/settings/connect-agent-light.png?fit=max\&auto=format\&n=Ndtg9NEpwGc2OULA\&q=85\&s=1caab1852f8afaa6bdb69faebbc2b1ca)

Connect an agent — Forge Console at `/settings/connect-agent`

## What you can do

* Copy your deployment's MCP endpoint and choose which jobs your host lists. See [Choose the connection](#choose-the-connection).
* Connect Claude Code, Claude Desktop / claude.ai, VS Code or Cursor with sign-in or a static key. See [Sign in when the deployment offers it](#sign-in-when-the-deployment-offers-it) and [Use a static credential](#use-a-static-credential).
* Verify the connected actor and its access before a write. See [Verify and recover](#verify-and-recover).

## Choose the connection

1. Copy the **MCP Endpoint URL** shown in Console. Use that value rather than guessing a deployment hostname.
2. In **Choose what your agent lists**, keep `start` for a first connection or select the jobs relevant to your work.
3. In **Add Forge to your host**, choose **Claude Code**, **Claude Desktop / claude.ai**, **VS Code**, or **Cursor**.
4. Follow that host's generated recipe. Its URL includes the listing jobs you selected.

The available jobs are `start`, `access`, `work`, `approvals`, `find`, `run`, `explain`, and `knowledge`. They select which tools the host lists. They do not widen roles, credential scopes, or the operations allowed by governance. With no job selected, the connection lists `start`.

## Sign in when the deployment offers it

When interactive sign-in is configured, **Sign in from your MCP host** appears and host recipes default to **Sign in**:

1. Add the server using the recipe; no static key is needed for that mode.
2. Complete the host's browser sign-in with your active Forge account.
3. Open **Settings → Personal keys → Host sign-ins** and grant the sign-in its required scopes. A new host sign-in starts with no scopes and cannot perform operations yet.
4. Reconnect or refresh the host's tool list and verify its reported Forge identity and effective access.

Revoke the sign-in from Personal keys to stop subsequent requests. Delete a revoked sign-in if you need to establish that host connection again.

If Console says interactive sign-in is unavailable, choose the static-key recipe. The page's sign-in availability reflects deployment configuration; it is not evidence that your account has permission to use a particular operation.

## Use a static credential

Create a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md) for your own access and choose **Static key** where the mode selector is available. Copy the recipe without replacing its environment-variable or password-input placeholder with a committed secret.

| Host | Where the generated recipe belongs |
| - | - |
| Claude Code | The terminal command or project `.mcp.json`; static recipes use `FORGE_MCP_KEY`. |
| Claude Desktop / claude.ai | The custom connector settings and the endpoint shown by Console. |
| VS Code | Workspace `.vscode/mcp.json`; the static recipe prompts for the key. |
| Cursor | Project `.cursor/mcp.json` or the user-level equivalent; the static recipe reads the key from the environment. |

An External App can also supply a `client_credentials` bearer token. It acts as the application, not as your person. The host must replace expired tokens; this page does not refresh them. See the [MCP host quickstart](https://docs.gloo.com/forge/quickstart/mcp-host.md) for current authentication modes and qualification limits.

## Verify and recover

After connection, ask the host to identify the Forge actor and inspect its effective permissions before performing a write. A visible tool is not proof that the credential can invoke every operation behind it.

| Symptom | Check |
| - | - |
| The host cannot reach Forge | Confirm the displayed endpoint, network reachability, and the host's transport configuration. A cloud-hosted connector must reach the endpoint from its own network. |
| Sign-in works but operations are refused | Check Host sign-in scopes, your current role grants, and the resource scope in [Your access](https://docs.gloo.com/forge/console/settings/your-access.md). |
| A static connection gets `401` | Check the bearer value, expiration, revocation, and whether an External App token needs replacement. |
| Too many or too few tools are listed | Revisit listing jobs and refresh the host's connection. Changing jobs does not change authorization. |
| A write asks for confirmation | Inspect the proposed operation and current [MCP contract](https://docs.gloo.com/forge/reference/mcp-server.md); do not treat confirmation as an authentication error. |

## Key state to watch

* **A new host sign-in has no scopes** — grant them under **Settings → Personal keys → Host sign-ins** before it can act.
* **`401` on a static connection** — check the key's value, expiry and revocation.
* **Listed tools** — jobs change which tools the host lists, never what it is allowed to do.

Keep secrets out of chat messages, screenshots, and shared project files. For API-only software, use [External Apps](https://docs.gloo.com/forge/console/platform/external-apps) rather than treating a personal host connection as an application identity.

## Related surfaces

* [Personal keys](https://docs.gloo.com/forge/console/settings/personal-keys.md): the key an external agent connects with.
* [Forge MCP](https://docs.gloo.com/forge/console/platform/forge-mcp.md): the MCP server an agent connects to.
* [Your access](https://docs.gloo.com/forge/console/settings/your-access.md): the roles the agent acts with.


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