Connect Gesta MCP

Gesta MCP gives a coding agent controlled access to Gesta data and governance tools. Use it to review Recaps and Team Overview, inspect organization rules, and manage supported governance resources without leaving Codex or Claude Code.

One MCP connection covers every organization available to your Gesta account. The connection uses the shared /mcp endpoint; it is not tied to the organization open in the Console.

Before you begin

You need:

• a Gesta account with an active organization membership;
• Codex or Claude Code installed on the machine;
• a browser for OAuth authorization.

Members can list their organizations and request their own Recaps. Team-wide observability and organization governance tools require the Owner role.

Connect with one prompt

Copy this prompt into Codex or Claude Code:

Connect Gesta MCP to this coding agent.

Server name: gesta
Server URL: https://console.gesta.run/mcp
OAuth scopes: openid, offline_access, gesta:mcp:read, gesta:mcp:write

Use the profile matching this coding agent:
- Codex: client ID gesta-codex, callback port 34123
- Claude Code: client ID gesta-claude-code, callback port 34124

Use this coding agent's supported MCP configuration command, then start OAuth login and let me complete authorization in the browser. This is one shared connection for all organizations available to my account. When a tool needs an organization, call list_organizations and pass its returned slug as organization_slug; do not ask me to reconfigure the server URL.

Let the coding agent configure the server, then complete authorization in the browser. Start a new agent session afterward so the connected tools are loaded.

For preproduction or self-hosted Gesta, copy the prompt from Settings → MCP instead. The Console substitutes the correct MCP URL for that environment.

Authorization is stored by the coding agent. Do not paste tokens or callback URLs into source control, tickets, or chat.

If the agent's command fails

Some agents try to register a new OAuth client at connection time. Gesta uses pre-registered client profiles instead, so that attempt fails with Incompatible auth server: does not support dynamic client registration.

Claude Code accepts the registered profile directly. Pick the scope that suits how you work, then run:

claude mcp add --scope <local|project|user> --transport http \
  --client-id gesta-claude-code --callback-port 34124 \
  gesta https://console.gesta.run/mcp

For Codex, use client ID gesta-codex and callback port 34123 with that agent's own MCP configuration method.

Select an organization

The shared MCP endpoint has no implicit current organization. Before calling an organization-scoped tool, the agent must:

1. call list_organizations;
2. select the intended organization from the result;
3. pass its slug as organization_slug to the next tool.

Do not create a separate MCP server or change the server URL when switching organizations. Gesta verifies the signed-in user's active membership on every organization-scoped call.

For example, ask:

List my Gesta organizations, then show the 30-day Team Overview for Acme.

If more than one organization has a similar name, the agent should show the matching names and slugs before continuing.

Available capabilities

get_team_overview supports 7-, 30-, and 90-day windows and defaults to 30 days. List tools return bounded results; when has_more is true, continue with the returned next_cursor. A truncated result means the response reached a configured safety bound, not that the organization has no additional data.

Updates require the latest observed updated_at value. If another user changes the resource first, read the current resource again before retrying. Permanent deletion requires the user to confirm the exact resource before the agent can send confirm: true.

Troubleshooting

The coding agent shows Not logged in

Paste the setup prompt into the coding agent again and ask it to reconnect gesta. Complete browser authorization when prompted.

Setup fails with "does not support dynamic client registration"

The agent tried to create an OAuth client at connection time. Gesta issues pre-registered client profiles instead. Reconnect with the profile set explicitly, as described in If the agent's command fails.

OAuth cannot open the callback port

Confirm that another process is not using port 34123 for Codex or 34124 for Claude Code, then retry login. Do not substitute a random port; the callback must match the registered client profile.

Gesta tools do not appear

Ask the coding agent to verify that the gesta server is enabled. Start a new agent session after configuration because an existing session may not reload its MCP tool list.

A tool returns Forbidden

Call list_organizations again and use the returned slug. Confirm that the signed-in identity is still an active member of the organization. Team and governance operations also require the Owner role; writes additionally require the gesta:mcp:write scope.

The server uses an organization-specific URL

Replace legacy URLs containing /mcp/v1/orgs/ with the exact shared /mcp URL from Settings → MCP, then authorize again. Organization selection belongs in the organization_slug tool argument, not in the server URL.

Related guides

• Review Security and privacy before enabling broad access.
• Use MCP and tools to observe external MCP servers and tool usage across enrolled agents.
• See Organization Library for the governance resources exposed through Gesta MCP.