Connect an MCP client

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
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
Claude Code
Cursor
VS Code

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:

Go to Customize > Connectors and click Add custom connector.
Enter https://api.guild.ai/mcp as the server URL.
If Claude asks how to identify itself, choose Register automatically.
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 mcp add --transport http guild https://api.guild.ai/mcp

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

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

{
  "mcpServers": {
    "guild": {
      "url": "https://api.guild.ai/mcp"
    }
  }
}

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

{
  "servers": {
    "guild": {
      "type": "http",
      "url": "https://api.guild.ai/mcp"
    }
  }
}

Approve access

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

Sign in to Guild if you aren’t already.
Review the page that reads wants access to your Guild account. It lists the permissions requested and where Guild sends you back.
Click Allow.

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

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

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.
Register. The client registers itself with POST /v1/oauth/register (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.
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.
Exchange. The client exchanges the code at https://api.guild.ai/v1/oauth/token. Access tokens last one hour; refresh tokens last 90 days.
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

Install the CLI and sign in:
npm i -g @guildai/cli guild auth login
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
Cursor
VS Code

claude mcp add guild -- guild mcp

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

{
  "mcpServers": {
    "guild": {
      "command": "guild",
      "args": ["mcp"]
    }
  }
}

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

{
  "mcpServers": {
    "guild": {
      "command": "guild",
      "args": ["mcp"]
    }
  }
}

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

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

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:

claude mcp add --transport http guild-docs https://docs.guild.ai/mcp

Get Started

OAuth

Workspaces

Triggers

Agents

Agent versions

Sessions

Skills

Integrations

Accounts

Organizations and users

Customer connectors

Connect an MCP client

Hosted server

Add the server

Approve access

Permissions

What the tools do

How the OAuth flow works

Local server

Set it up

Search these docs over MCP

​Hosted server

​Add the server

​Approve access

​Permissions

​What the tools do

​How the OAuth flow works

​Local server

​Set it up

​Search these docs over MCP

Hosted server

Add the server

Approve access

Permissions

What the tools do

How the OAuth flow works

Local server

Set it up

Search these docs over MCP