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

# Connect an MCP client

> Connect Claude, Claude Code, Cursor, or VS Code to Guild over MCP, using the hosted server with OAuth or the local server in the Guild CLI.

Guild exposes its operations as MCP (Model Context Protocol) tools, so an MCP client such as Claude, Claude Code, Cursor, or VS Code can read and act on your agents, workspaces, sessions, and triggers. You can connect in two ways:

| | Hosted server | Local server |
| - | - | - |
| Address | `https://api.guild.ai/mcp` | `guild mcp`, run by your client over stdio |
| Install | Nothing | The [Guild CLI](/cli/getting-started) |
| Sign in | OAuth in your browser, the first time your client connects | `guild auth login` |
| Acts as | You, limited to the permissions you approve | You, through the CLI's session |
| Best for | Any MCP client, including ones that can't run local commands | Coding assistants that already run the Guild CLI |

## Hosted server

The hosted server speaks streamable HTTP at `https://api.guild.ai/mcp`. Your client needs only the URL: it discovers the OAuth settings from the server and registers itself.

### Add the server

**Claude**

Add Guild as a custom connector. It works in Claude Desktop and on claude.ai, since both use your Claude account.

On a Free, Pro, or Max plan:

1. Go to **Customize > Connectors** and click **Add custom connector**.
2. Enter `https://api.guild.ai/mcp` as the server URL.
3. If Claude asks how to identify itself, choose **Register automatically**.
4. Click **Add**, then click **Connect** next to Guild.

On a Team or Enterprise plan, an Owner adds the connector once for the organization under **Organization settings > Connectors**: select **Add**, then **Custom**, and enter `https://api.guild.ai/mcp`. Each member then clicks **Connect** next to Guild under **Customize > Connectors**.

To use Guild in a chat, click **+**, select **Connectors**, and turn Guild on.

**Claude Code**

```bash theme={null}
claude mcp add --transport http guild https://api.guild.ai/mcp
```

Then run `/mcp` in Claude Code, select **guild**, and choose **Authenticate**.

**Cursor**

Add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project:

```json theme={null}
{
  "mcpServers": {
    "guild": {
      "url": "https://api.guild.ai/mcp"
    }
  }
}
```

**VS Code**

Add the server to `.vscode/mcp.json` in your workspace:

```json theme={null}
{
  "servers": {
    "guild": {
      "type": "http",
      "url": "https://api.guild.ai/mcp"
    }
  }
}
```

### Approve access

The first time your client connects, it opens Guild in your browser:

1. Sign in to Guild if you aren't already.
2. Review the page that reads **{client} wants access to your Guild account**. It lists the permissions requested and where Guild sends you back.
3. Click **Allow**.

Your client then connects and lists the Guild tools. It acts as you, limited to the permissions you approved.

> [!NOTE]
>
> Guild has not verified most MCP clients, so the consent page shows **Guild has not verified this application**. Only continue if you started the connection from a client you trust.

To remove a client's access, open **Security** in your personal account and click **Disconnect** next to it under [Connected apps](/platform/security-settings#connected-apps). It loses access right away.

### Permissions

The server asks for the scopes its tools use:

| Scope | Lets the client |
| - | - |
| `agents:read` | List and read agents, their versions, and their build and publish jobs |
| `agents:write` | Create agents, commit versions, and publish, archive, or tag them |
| `workspaces:read` | List and read workspaces, installed agents, members, context, and triggers |
| `workspaces:write` | Create workspaces, install and configure agents, set context, and schedule, pause, or resume triggers |
| `sessions:read` | Read sessions and their events |
| `sessions:write` | Start sessions and send messages |
| `skills:read` | List and read skills |
| `skills:write` | Create skills and add versions |
| `integrations:read` | Search integrations and the tools they provide |
| `organizations:read` | Read your organizations and their members |

The tools the server offers change as Guild adds them. Your client lists the current set when it connects.

### What the tools do

Each tool runs one Guild API call as you, so it can reach only what your account and the approved scopes allow.

| Area | What you can ask for |
| - | - |
| Agents | List, read, and create agents; configure an agent from a prompt and tools; archive, restore, or tag one |
| Agent versions | Read a version and its code; commit a new version; follow its validation and publish steps; publish or unpublish it |
| Workspaces | List, read, and create workspaces; see members; read and set the workspace context; install, update, or uninstall agents |
| Sessions | Start a test session for an agent, send it a message, and read its reply and events; list a workspace's sessions |
| Triggers | List and read triggers; schedule an agent; change, pause, or resume a schedule; list the sessions a trigger started |
| Skills | List, read, and create skills, and add versions |
| Integrations | Search integrations and list the tools each one provides |
| Account | See who you're connected as, and read users, your organizations, and their members |

Tools that only read are marked read-only, and tools that change or remove something are marked so your client can ask you before it runs them.

For example, you can ask your client to "create an agent that summarizes new GitHub issues, install it in my workspace, and schedule it every morning."

### How the OAuth flow works

You don't need this to connect a standard MCP client. It is here for anyone building their own.

1. **Discover.** An unauthenticated request to `https://api.guild.ai/mcp` returns `401` with a `WWW-Authenticate` header that points to the protected resource metadata at `https://api.guild.ai/.well-known/oauth-protected-resource/mcp`. That document names the authorization server, `https://api.guild.ai`, whose metadata is at `https://api.guild.ai/.well-known/oauth-authorization-server`.
2. **Register.** The client registers itself with [`POST /v1/oauth/register`](/api-reference/oauth/register-an-oauth-client) (dynamic client registration, RFC 7591). Every client is public: it gets no secret. Each redirect URI must use `https`, or `http` on a loopback address.
3. **Authorize.** The client sends the user to `https://api.guild.ai/v1/oauth/authorize` with a PKCE `S256` code challenge and the scopes it wants. The user approves on the consent page.
4. **Exchange.** The client exchanges the code at `https://api.guild.ai/v1/oauth/token`. Access tokens last one hour; refresh tokens last 90 days.
5. **Call.** The client sends the access token as `Authorization: Bearer <token>` on every request to `https://api.guild.ai/mcp`.

## Local server

The Guild CLI includes an MCP server that runs on your machine over stdio. It uses your CLI sign-in and defaults to your configured workspace.

### Set it up

1. Install the CLI and sign in:

   ```bash theme={null}
   npm i -g @guildai/cli
   guild auth login
   ```

2. Add the server to your client. In a project, `guild setup` does this for Claude Code: it writes the server to `.mcp.json` along with Guild's coding skills. To add it by hand instead:

**Claude Code**

```bash theme={null}
claude mcp add guild -- guild mcp
```

Or add it to `.mcp.json` in your project root:

```json theme={null}
{
  "mcpServers": {
    "guild": {
      "command": "guild",
      "args": ["mcp"]
    }
  }
}
```

**Cursor**

Add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "guild": {
      "command": "guild",
      "args": ["mcp"]
    }
  }
}
```

**VS Code**

Add the server to `.vscode/mcp.json` in your workspace:

```json theme={null}
{
  "servers": {
    "guild": {
      "type": "stdio",
      "command": "guild",
      "args": ["mcp"]
    }
  }
}
```

To pin the server to a workspace other than your configured one, add `"--workspace", "<workspace-id-or-name>"` to `args`. If the server fails to start with `Not authenticated`, run `guild auth login` again.

The local server's tools, their parameters, and what they return are listed in [MCP server](/cli/mcp-server).

## Search these docs over MCP

These docs have their own MCP server at `https://docs.guild.ai/mcp`, with no sign-in. It searches and reads this documentation, so a coding assistant can look things up while it works:

```bash theme={null}
claude mcp add --transport http guild-docs https://docs.guild.ai/mcp
```