> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# guild gateway

> Manage MCP gateway profiles and connect Claude Code or Codex to one.

Manage [MCP gateway](/platform/mcp-gateway.md) profiles, and point a local assistant at one. Commands address a profile as `owner~workspace~profile`, such as `acme~team-ws~eng-tools`.

## install

```bash theme={null}
guild gateway install <client> [profile]   # Point a local assistant at a profile
```

`install` registers an MCP server named `guild-gateway` in the assistant's configuration. Before it writes anything, it checks that it can reach the profile's endpoint. Then it warns you about any service on the profile that has no credential for you.

```bash theme={null}
# Choose a profile from a searchable list
guild gateway install claude

# Pass the profile directly
guild gateway install claude acme~team-ws~eng-tools

# Replace an existing guild-gateway server without asking
guild gateway install claude acme~team-ws~eng-tools --force
```

| Argument | Description |
| - | - |
| `<client>` | The assistant to configure: `claude` or `codex`. |
| `[profile]` | The profile, as `owner~workspace~profile`. Omit it to choose from a list, which needs an interactive terminal. |

| Option | Description |
| - | - |
| `--force` | Replace an existing `guild-gateway` server without asking. |
| `--scope <scope>` | Where Claude Code stores the server: `user` (default), `project`, or `local`. Codex keeps MCP servers only in `~/.codex/config.toml`, so it rejects this option. |

> [!NOTE]
>
> To connect Codex, copy the command from the **Codex** tab of the profile's **Connect** card. It reads your token from the `GUILD_TOKEN` environment variable. See [Connect an assistant](/platform/mcp-gateway.md#codex).

## profile

```bash theme={null}
guild gateway profile list                              # Profiles you can reach
guild gateway profile list --workspace acme~team-ws     # Only one workspace
guild gateway profile show acme~team-ws~eng-tools       # Services and your credential state
guild gateway profile create acme~team-ws eng-tools     # Create a profile
guild gateway profile delete acme~team-ws~eng-tools     # Delete, after a prompt
guild gateway profile delete acme~team-ws~eng-tools --force   # Delete without asking
```

`list` and `show` print each profile's page in Guild. `show` also lists the profile's services, whose credential each runs with, and whether you have one. It ends with the MCP endpoint:

```text theme={null}
acme~team-ws~eng-tools  b1f0...

┌─────────────┬─────────────────────┬─────────────────┐
│ SERVICE     │ RUNS AS             │ YOUR CREDENTIAL │
├─────────────┼─────────────────────┼─────────────────┤
│ acme~github │ your own credential │ missing         │
│ acme~slack  │ a shared credential │ connected       │
└─────────────┴─────────────────────┴─────────────────┘

Manage in Guild: https://app.guild.ai/organizations/acme/workspaces/team-ws/gateway/eng-tools
MCP endpoint:    https://gateway.guild.ai/workspaces/acme~team-ws/mcp/eng-tools
```

Connecting a credential happens in the browser, so the CLI doesn't do it. Use `show` to find services marked `missing`, then follow the **Manage in Guild** link to connect them.

## profile integration

```bash theme={null}
guild gateway profile integration add acme~team-ws~eng-tools acme~github \
  --required-credentials-mode member

guild gateway profile integration update acme~team-ws~eng-tools acme~github \
  --required-credentials-mode shared

guild gateway profile integration remove acme~team-ws~eng-tools acme~github
```

Pass the integration as its ID or full name, such as `acme~github`. `--required-credentials-mode` is required for `add` and `update`:

| Value | In the app | Meaning |
| - | - | - |
| `member` | **Personal** | Each person connects their own account. |
| `shared` | **Shared** | An admin connects one credential for everyone. |

## Global options

Add `--json` to `list` and `show` for machine-readable output.