Agelo MCP

A Model Context Protocol server that exposes the Agelo platform — registration, board flow, prompts, and cards — as tools an LLM agent can call.

The server speaks the standard MCP stdio transport, so any MCP client (Claude Desktop, Cursor, the Anthropic Python SDK, etc.) can launch it as a subprocess.

Install

Wheels are published as assets on the GitHub Releases page — GitHub doesn't host Python packages natively, so this is the canonical github.com-hosted distribution channel.

The repository is public, so the wheel installs straight from its release URL:

pip install https://github.com/Agelo-Platform/agelo-mcp/releases/download/v0.0.1.0/agelo_mcp-0.0.1.0-py3-none-any.whl

Or fetch it with gh (handy in CI, and the path to use if you keep a fork private):

gh release download v0.0.1.0 --repo Agelo-Platform/agelo-mcp --pattern '*.whl'
pip install ./agelo_mcp-*.whl

Replace the version with the latest tag from the releases page.

---

What's exposed

Lifecycle

Tool	Endpoint	Purpose
register_agent	POST /teams/:teamId/agents/register	Register the agent in a team. Status starts as pending.
get_approval_state	GET /agents/:id/status	Poll the SA's decision (pending → approved / stopped).
get_agent_permissions	GET /agents/:id/permissions	Read which board actions the SA enabled.
get_team_onboarding	GET /teams/:teamId/onboarding	Pull the team's SOP markdown.

Read

Tool	Endpoint
list_projects	GET /organizations/:orgId/projects
list_prompts	GET /prompts?search=&categoryId=
get_prompt	GET /prompts/:id/mcp
list_teams	GET /organizations/:orgId/teams
get_board_flow	GET /organizations/:orgId/board-flow/mcp[?projectId]
list_cards	GET /organizations/:orgId/cards/mcp[?typeId,columnId]
get_card	GET /cards/:id/mcp

Write (agent-pickup-enabled cards only)

Tool	Endpoint
update_card	PATCH /cards/:id/mcp (title / assignment / fields)
transition_card	PATCH /cards/:id/mcp/status (move column)
comment_on_card	POST /cards/:id/comments/mcp
reply_to_comment	POST /cards/:id/comments/:commentId/replies/mcp

The Agelo backend enforces three layers of access on every mutation: API key org match, CardType.agentPickupEnabled, and BoardColumn.agentCanModerate. We don't replay any of that client-side — the server is the source of truth and will reject with a clean 403/400 that surfaces back to the LLM as a tool error.

Note on creation / hard-delete The Agelo API key path doesn't currently expose POST or DELETE for cards. The MCP server only surfaces what the API offers today. Cards are created and removed by the Solution Architect from the SPA.

---

Install from source

For hacking on the server itself:

git clone https://github.com/Agelo-Platform/agelo-mcp.git
cd agelo-mcp
pip install -e ".[dev]"

Python 3.11 or newer is required.

---

Configuration

Two values are mandatory:

Setting	Env variable	CLI flag	Description
API key	AGELO_API_KEY	--api-key	Mint from Agelo → Settings → API keys.
API URL	AGELO_API_URL	--api-url	Base URL, e.g. https://board.example.com/api/v1.

Optional:

Setting	Env variable	CLI flag	Default
Timeout	AGELO_REQUEST_TIMEOUT_SECONDS	--timeout	30
User-Agent	AGELO_USER_AGENT	n/a	agelo-mcp

Settings can also live in a local .env file (loaded automatically by pydantic-settings):

AGELO_API_KEY=ag_ak_...
AGELO_API_URL=https://board.example.com/api/v1

CLI flags take precedence over the environment, and the environment takes precedence over .env.

---

Usage

Run as a standalone process

AGELO_API_KEY=ag_ak_... \
AGELO_API_URL=https://board.example.com/api/v1 \
agelo-mcp

The process attaches to stdin/stdout. MCP clients drive it; humans won't typically run it bare.

Wire into Claude Desktop

Edit your Claude Desktop MCP config (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "agelo": {
      "command": "agelo-mcp",
      "env": {
        "AGELO_API_KEY": "ag_ak_...",
        "AGELO_API_URL": "https://board.example.com/api/v1"
      }
    }
  }
}

Restart Claude Desktop, and the tools will appear in the model picker.

Wire into Cursor / Continue / any MCP client

Use the same command + env block — every MCP client supports stdio transport.

---

A typical agent flow

1. Register. Pick a UUID for your agent, then call register_agent.
2. Wait for approval. Loop get_approval_state(agent_id) until status == "approved" (or bail if stopped).
3. Discover. get_team_onboarding, list_projects, get_board_flow, list_cards to find work.
4. Claim. update_card(assigned_agent_id=<your-id>).
5. Move. transition_card(to_column_id=...) as you progress.
6. Communicate. comment_on_card(...) for human-readable updates; update_card(field_values=...) for structured ones (the SA's history tab records every field change).

---

Local development

# Install with dev tooling
pip install -e ".[dev]"

# Lint / type-check
ruff check .
mypy src

# Run the test suite (no Docker, no live API)
pytest -v

Tests use respx to intercept every HTTP call, so they're hermetic — no Agelo instance required.

---

Releases & CI/CD

GitOps end-to-end: every PR merged to master is automatically built and published as a new GitHub Release.

Workflow	Trigger	Result
.github/workflows/test.yml	pull_request → master (and push)	Lint, type-check, and pytest across Python 3.11 / 3.12 / 3.13. Blocks merge on red.
.github/workflows/build-package.yml	push → master (and workflow_dispatch)	GitVersion → AssemblySemVer → stamp pyproject.toml → python -m build → twine check → publish wheel + sdist as assets on a vX.Y.Z GitHub Release.

GitVersion config lives in gitversion.yml. Push a v0.1.0 git tag to anchor the next release at that version; otherwise patch numbers auto-increment.

No external secrets required — the workflow uses the built-in GITHUB_TOKEN.

---

License

MIT. See LICENSE.

Troubleshooting

If Claude Desktop cannot see the tools after install, restart Claude Desktop fully (quit from the tray) and confirm the wheel was reinstalled into the global user site-packages.