Agents (MCP)

Let Claude, Codex or any MCP agent run your guild.

The Guild MCP server lets an AI agent run your guild for you. Claude, Claude Code, Codex, Cursor and any other agent that speaks the Model Context Protocol (MCP) can connect to it at https://mcp.guild.xyz/mcp, then create roles, set up requirements and rewards, edit pages, read analytics and more, by asking in plain language. It's free on every plan.

Agents are in beta: the tools an agent can use and what they return may still change. Changes an agent makes to guild settings, roles, points and form reviews are in the audit log, and you can revoke a connection at any time.

How it works

You connect an agent once, from the agent. It sends you to Guild to sign in, you choose a guild and what the agent may do there, and from then on the agent acts as you, in that guild only, within those limits. Its changes to guild settings, roles, points and form reviews appear in the guild's Audit log, marked as made by that agent on your behalf. Changes to pages, requirements, reward settings, spaces and proposals are not in the audit log yet.

Ask it things like "Create a Holders role for anyone with at least 1 of our NFTs on Base". The admin's Agents page has more examples under Then ask it.

Connect your agent

The server is https://mcp.guild.xyz/mcp.

Claude

1. In Claude, open Settings, then Connectors, and add a custom connector with this link:

   https://mcp.guild.xyz/mcp
   

2. Press Connect and sign in to Guild.

Claude Code

1. Run this in your terminal:

   claude mcp add --transport http guild https://mcp.guild.xyz/mcp
   

2. In Claude Code, type /mcp, choose guild and sign in.

Codex

1. Add this to ~/.codex/config.toml:

   [mcp_servers.guild]
   url = "https://mcp.guild.xyz/mcp"
   

2. Sign in from your terminal:

   codex mcp login guild
   

Other

1. Add this link where your assistant connects to MCP servers:

   https://mcp.guild.xyz/mcp
   

2. Sign in to Guild when it asks.

Connect from Claude

1. In Claude, open Settings, then Connectors, and add a custom connector with the link https://mcp.guild.xyz/mcp.
2. Press Connect and sign in to Guild.

The admin's Agents page has the same two steps for Claude Code, Codex and other agents.

Build a progression path

A role can require another role, so members climb from one to the next: Newcomer, then Regular, then Veteran. Ask your agent "How do I link roles in a progression path?", or tell it the levels you want. It creates the roles, makes each one require the role before it, and puts them on the page in order. You can also ask it to reorder the roles on any page.

Change how a page looks

Your agent can set everything on the Spaces & roles screen for a page. That covers its layout (list, cards, grid, path, spotlight or comparison, with each layout's options), the order of its roles, who can see it (everyone, holders of certain roles, or admins only), its place in the guild's navigation, and whether it carries a feed, announcements or a chat. Try "Show the Levels page as a path" or "Only let Builders see the Alpha page".

More your agent can manage

Beyond roles and pages, an agent can claim or release your vanity alias, set the animated banner, add or archive custom emoji, create and edit your launch page (and launch now), change referral settings, read the referral leaderboard, manage guild profile items and set a role's member limit or reserved numbers. Reading or changing individual members' data needs the member permissions: point balances and the points ledger, granting or deducting points, pre-registrations, member numbers and who voted on a proposal. Agents still never cast votes.

Approve the connection

When you sign in from the agent, Guild opens a consent page on guild.xyz that shows which app is asking and where it will return.

1. Tick the permissions to grant. The ones the app asked for are ticked already; permissions that read member data are never pre-ticked, so you add them on purpose.
2. Pick the guild. You can only pick a guild you own or administer.
3. Press Connect app.

One connection, one guild

A connection manages exactly one guild, chosen when you approve it, and that can't be changed later. To manage a second guild, connect the agent again and pick the other guild. You must still be an owner or admin of the guild whenever the agent acts; if you lose admin rights, so does the agent.

Permissions

You choose what an agent may do when you approve it, and can narrow it later from the admin's Agents page. These are the permissions the server knows today:

What agents can never do

Whatever you allow, the server refuses these:

• Agents cannot delete a guild.
• An agent manages the one guild it is connected to; create the guild in Guild, then connect the agent to it.
• Agents cannot manage guild API keys.
• Agents cannot reset a points platform.
• Agents cannot manage agent access.
• Agents cannot join guilds for their user.
• Agents cannot leave guilds for their user.
• Agents cannot claim roles for their user.
• Agents cannot fill in forms for their user.
• Agents cannot export to their user's Google account; use the CSV export.
• Agents cannot react, report or mark messages read for their user.
• Agents cannot vote for their user.
• Agents cannot change their user's profile level.
• Profile levels are read by Guild's requirement service only.
• Agents cannot use Guild staff tools.
• Agents cannot change the guild's owner, admins, plan or verification.

Manage and revoke agents

The admin's Agents page lists every agent that can act on the guild under Connected agents, whoever connected it, with its permissions, who connected it and when it was last used. You can rename your own connections, take permissions away, or Revoke them. Revoking stops the agent within 15 seconds; the changes it already made stay, and the audit log keeps them. To give an agent more permissions, connect it again. Connections made by other admins are shown read-only: only the admin who connected an agent can rename it or change its permissions. The guild owner can also revoke any admin's connection.

Access tokens for headless use

Scripts, CI and agents that can't open a browser use an access token instead of signing in. On the Agents page, open For developers and press Access token; name it, pick its permissions and an expiry of 30, 90 or 365 days. The token works for this guild only, and it's shown once: Guild keeps only a fingerprint of it. Send it as a Bearer token to the server URL.

Every action

The Guild API routes an agent can call, and the permission each needs: