Skip to main content
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 (dark)Connect an agent (light)

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

What you can do

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

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 rather than treating a personal host connection as an application identity.