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

# MCP gateway

> Give Claude Code, Codex, or any MCP client one endpoint that reaches a workspace's integrations, with Guild's credentials, policies, and audit trail behind it.

The MCP gateway gives any MCP client one HTTP endpoint that reaches a workspace's integrations through Guild. Point Claude Code, Codex, Claude, ChatGPT, Cursor, or your own script at a URL. Guild picks the credential for each call, applies your [credential policies](/platform/credential-policies.md), and records what ran.

You configure the gateway with **profiles**. A profile is a named set of integrations inside a workspace. For each integration, it says whether people connect their own accounts or share one credential.

Each profile has its own endpoint:

```text theme={null}
https://gateway.guild.ai/workspaces/{owner}~{workspace}/mcp/{profile}
```

A profile holds no credentials itself. Each person who calls it uses their own Guild identity, so two people on the same profile reach GitHub as themselves.

## Open the gateway

Open a workspace, then click **Gateway** in the workspace sidebar. The **MCP Gateway** page lists every profile in the workspace, with **Your profiles** first and **From others** after.

## Who can do what

| Action | Who |
| - | - |
| Create a profile | Anyone who can edit the workspace |
| Add, switch, or remove a profile's integrations | The profile's creator, or an admin of the account that owns the workspace |
| Connect a **Personal** integration | Each person, for themselves |
| Connect a **Shared** integration | An admin of the account that owns the workspace |
| Use the profile's endpoint | Anyone who can reach the workspace |
| Delete a profile | The profile's creator, or an admin |

## Create a profile

**1. Start the profile**

On the **MCP Gateway** page, click **New profile**.

**2. Name it**

Enter a **Name**, such as `eng-tools`. Use lowercase letters, numbers, hyphens, underscores, and periods. The name must be unique in the workspace.

**3. Create it**

Click **Create profile**. Guild opens the profile page.

## Add integrations

**1. Open the dialog**

On the profile page, click **Add integration**.

**2. Pick integrations**

Select one or more of the workspace's integrations. Use **Search integrations** to filter the list.

**3. Choose who connects each**

For each integration, choose **Personal** or **Shared**.

**4. Add them**

Click **Add**.

| Mode | Who connects | Use it when |
| - | - | - |
| **Personal** | Each person connects their own account. | Calls should run as the person making them, such as GitHub or Linear. |
| **Shared** | An admin connects once for everyone on the profile. | Everyone should use one service account, such as a monitoring or ticketing bot. |

To change a mode later, open the integration's row menu and choose a different option under **Who connects**. To take an integration off the profile, choose **Remove from profile**.

## Connect credentials

An integration only works for you once it has a credential. The profile header shows how many are ready, such as **2 of 3 connected**, and how many need you.

* **Personal rows:** click **Connect** on the row. Guild sends you through the service's sign-in.
* **Shared rows:** an admin clicks **Connect for everyone**. If you aren't an admin, click **Ask an admin** to copy a link to send to one.

On someone else's profile, the header counts only the **Shared** rows, because other people's personal credentials aren't visible to you.

### Use a different credential

By default, a profile uses the same credential as the rest of the workspace. To change that for one integration, open its row menu and choose **Use a different credential…**:

* Pick one of your existing credentials to pin it to this profile only. Your other profiles and agents keep their own.
* Choose **Add a dedicated credential…** to connect one that only this profile can use.
* Choose **Default** to go back to the workspace's credential.

Switching away from a dedicated credential deletes it, and you can't undo that.

For how Guild picks a credential when nothing is pinned, see [How Guild chooses a credential](/platform/credentials.md#how-guild-chooses-a-credential).

## Connect an assistant

The profile page's **Connect** card has a tab for each kind of client: **Claude Code**, **Codex**, and **Other**. Each tab gives you a command or URL to copy.

### Claude Code

Run the install command from the **Claude Code** tab, or run it yourself with the [Guild CLI](/cli/commands/gateway.md):

```bash theme={null}
guild gateway install claude acme~team-ws~eng-tools
```

The command registers an MCP server named `guild-gateway` in Claude Code. Before it writes anything, it checks that it can reach the endpoint. It also warns you about any integration on the profile that has no credential for you yet.

Leave out the profile to choose one from a searchable list:

```bash theme={null}
guild gateway install claude
```

### Codex

Copy the command from the **Codex** tab. It registers the same `guild-gateway` server and reads your Guild token from the `GUILD_TOKEN` environment variable:

```bash theme={null}
codex mcp add guild-gateway \
  --url https://gateway.guild.ai/workspaces/acme~team-ws/mcp/eng-tools \
  --bearer-token-env-var GUILD_TOKEN
```

Set `GUILD_TOKEN` to the output of `guild auth token` before you start Codex.

### Other MCP clients

Copy the URL from the **Other** tab, or from the `MCP endpoint` line of `guild gateway profile show`. Add it as a custom MCP server or connector in your client.

The client must be able to reach `gateway.guild.ai`. A connector that runs on someone else's servers can reach it, but not a Guild deployment on your own network.

## What the client sees

The gateway exposes three tools, no matter how many integrations the profile holds. This keeps the client's tool list short.

| Tool | Arguments | Returns |
| - | - | - |
| `list_services` | None | The integrations on this profile |
| `list_tools` | `service`: a service name from `list_services` | The tools that service exposes, each with its input schema |
| `execute_tool` | `tool_name`: a name from `list_tools`. `arguments`: an object of the tool's arguments. | The tool's result |

For example, a client that wants to open a GitHub issue calls `list_services`, then `list_tools` for the GitHub service, then `execute_tool` with the issue tool's name and arguments.

## Review what ran

Every call runs under your Guild identity and appears in the workspace's [Sessions](/platform/sessions.md) list. There you can read back which tools the client called, with which arguments and which credential. Calls are grouped into one session per person per profile. After an hour with no calls, the next call starts a new session.

## Delete a profile

Open the profile's menu and choose **Delete profile**, then confirm. The profile's endpoint stops answering, so clients configured with it start failing. Its sessions and credential grants are kept for the audit trail.

## Troubleshooting

| Symptom | What to do |
| - | - |
| Every call returns `401` | The client's token expired or was never authorized. Run `guild gateway install` again with `--force`, or refresh `GUILD_TOKEN` for Codex. |
| A tool call fails with a missing credential | Run `guild gateway profile show <profile>` to see which service is missing. Connect **Personal** rows yourself on the profile page. **Shared** rows need an admin. |
| The profile page says **Profile not found** | The profile was deleted, or you're in a different workspace. |
| `guild gateway install` can't reach the URL | Check that your machine can reach `gateway.guild.ai`. |

## Related pages

* [`guild gateway`](/cli/commands/gateway) for the CLI commands
* [Credentials](/platform/credentials.md) for how credentials are owned and chosen
* [Credential policies](/platform/credential-policies.md) to limit what each credential can do
* [Integrations](/platform/integrations.md) to add services to the workspace first