MCP server: let Claude and other agents participate in your retros

Looptro ships a Model Context Protocol (MCP) server so AI agents (Claude Code, Cursor, or anything that speaks MCP) can read past retros, prepare new ones, and act on outcomes as first-class participants. Agents prep the ground, surface patterns, and follow up on action items so humans spend their retro time on the conversation.

If you’re building a non-agent integration, use the REST API instead. MCP is the right surface specifically for AI agents that need capability-scoped tool calls and audit trails.

Install

The MCP server is at https://app.looptro.dev/mcp on the same host as the app — JSON-RPC 2.0 over HTTP POST. Authentication is OAuth 2.0 with auto-discovery (RFC 9728 + RFC 8414): the client hits /mcp, gets a 401 with a WWW-Authenticate header that points at /.well-known/oauth-protected-resource, follows it through Dynamic Client Registration (RFC 7591) and either browser-based PKCE (RFC 7636) or the device-code flow (RFC 8628), then retries with a bearer token.

Claude Code:

claude mcp add looptro --url https://app.looptro.dev/mcp

That’s it. Claude Code handles the OAuth handshake itself. The first call opens a browser to Looptro’s consent page where you pick the team and approve the scopes the agent is asking for; subsequent calls reuse the token until it expires.

Headless agents (CLI, cron, container without browser): the same claude mcp add ... works. Claude Code detects there’s no browser and falls back to the device-code flow: the agent prints Open https://app.looptro.dev/device and enter ABCD-EFGH; you open the URL on any device, sign in, approve, and the agent picks up the token by polling /mcp/oauth/token.

Manual token (scripts that can’t do OAuth): mint a personal access token via POST /api/teams/{team_id}/agent-tokens with the scopes the script needs. The plaintext token is returned once in wire form rtl_pat_<id>_<secret>. Pass it as Authorization: Bearer <token> against /mcp directly. Same audit attribution as the OAuth path — both flows hash the secret with Argon2 and store rows in the same agent_tokens table.

Verify the connection

In Claude Code, run /mcp and you should see looptro listed with the scopes you approved. Ask the agent to call a tool:

Use the looptro tool to list our team's most recent five retros.

A 401 means the token’s not right (re-approve or regenerate). A 403 on a specific tool means the scope wasn’t in the token’s approved set — every failed tool call is audit-logged with the scope it was missing, so a quick look at the team’s audit timeline tells you what to grant.

What the agent can do

Tools cover the full retro workflow: prep, the retro itself, follow-up on action items, and ambient state like sprint cycles + summary narratives.

Scope	Tools
retros:read	list_retros, get_retro, get_summary
retros:write	create_retro, close_retro, update_retro_settings, set_summary_narrative, set_ready
posts:write	add_post, update_post, vote_on_post, group_posts, ungroup_posts, rename_group
action_items:read	get_action_items
action_items:write	create_action_item, update_action_item
templates:read	list_team_templates
templates:write	set_team_sprint_cycle

posts:read and action_items:read-style enumeration of individual resources is folded into get_retro — fetching a retro returns its full board (columns + posts + action items) so an agent doesn’t need a separate scope to enumerate them.

The MCP transport is JSON-RPC 2.0 over a single POST /mcp endpoint. The server implements initialize, tools/list, and tools/call. Tool descriptors are returned with full JSON Schema for the arguments — agents introspect and call without hardcoded shapes.

Every tool call writes an audit row tagged actor_type='agent' with the agent’s token id, the issuing user, the team, and (on failure) the error code. Agent actions sit alongside human actions in the same audit timeline.

Tokens

OAuth-issued tokens and manually-minted personal access tokens share the same backing table and the same enforcement model:

• Capability-scoped. The token only carries the scopes the user approved; a tool call missing the required scope returns a 403 with the scope name.
• Team-scoped. One token, one team. Multi-team agents install once per team. Cleaner audit trail.
• Revocable. Revoke any token via DELETE /api/teams/{team_id}/agent-tokens/{token_id}. A token management UI lives in team settings.
• Bounded expiry. Up to 365 days from creation; the manual-token path lets the user pick the exact expires_at. OAuth-issued bearers expire on the schedule the OAuth handshake negotiates.
• Rate-limited. Stricter than user sessions, per-token. Agents that exceed the budget get 429 back-pressure rather than silent failures.

What it doesn’t do

• Run a retro entirely without a human. Technically possible, not the product position. Agents prepare and assist; they don’t replace the team.
• Multi-team tokens. One token per team keeps the audit model clean.
• Stream partial tool results. The transport is JSON-RPC over HTTP POST: request / response, no SSE streaming for tool output. Server-initiated notifications (full Streamable HTTP) is a follow-up.
• MCP resources or prompts surface. Tools only at v1. The richer surface (read-only resources, canned prompt workflows) is on the post-MVP list.