@agilemonster/mcp-server
v1.0.35
Published
Official Model Context Protocol (MCP) server & Orchestrator for Agile Monster (Cursor, Claude Code, Antigravity, Codex, Hermes, Windsurf)
Maintainers
Readme
@agilemonster/mcp-server & Agent Orchestrator
Official Model Context Protocol (MCP) Server and Autonomous Agent Orchestrator for Agile Monster (https://app.agilemonster.com).
Seamlessly connects your Agile Monster boards with your favorite developer AI agents:
- Cursor
- Claude Code
- Antigravity / Gemini Code Assist
- Codex
- Hermes Agent
- Windsurf / Aider
⚡ Quick Start: Adding to your AI Agent
The quickest way is the one command in Connect a project folder below: it does everything in this section for you.
To set a tool up by hand, generate a Personal API Key in Agile Monster (https://app.agilemonster.com -> Profile -> AI Agents & API Keys -> Generate API key). Your key will look like am_live_....
1. Cursor (.cursor/mcp.json or Global Settings)
{
"mcpServers": {
"agilemonster": {
"command": "npx",
"args": ["-y", "@agilemonster/mcp-server"],
"env": {
"AGILEMONSTER_API_KEY": "am_live_your_token_here",
"AGILEMONSTER_API_URL": "https://api.agilemonster.com"
}
}
}
}2. Claude Code CLI
claude mcp add agilemonster npx -y @agilemonster/mcp-server \
-e AGILEMONSTER_API_KEY="am_live_your_token_here" \
-e AGILEMONSTER_API_URL="https://api.agilemonster.com"3. Antigravity / Gemini
Add to your Antigravity MCP directory (~/.gemini/antigravity/mcp/agilemonster or project settings):
{
"mcpServers": {
"agilemonster": {
"command": "node",
"args": ["/path/to/agilemonster/packages/mcp-server/bin/mcp.js"],
"env": {
"AGILEMONSTER_API_KEY": "am_live_your_token_here",
"AGILEMONSTER_API_URL": "https://api.agilemonster.com"
}
}
}
}📁 Connect a project folder (bootstrap)
Open a terminal in your project folder and run this once (it needs Node.js 18.14 or newer):
npx -y @agilemonster/mcp-server bootstrapIt asks for your API key the first time, lets you pick the board, writes the files below, installs the
background runner (see the next section) and then gets a coding agent ready: it shows which agents on
this computer can work a card, offers to sign in each one that is installed but signed out (in that agent's
own sign-in; Agile Monster never sees a password), and, if none is installed, offers to install one.
init and setup are the same command. Add --board="Board name" to skip the question, --no-service to
leave the background runner out, or --no-login to skip the sign-in offer. To come back to the sign-in step
later:
npx -y @agilemonster/mcp-server agents loginThis generates:
.agilemonster.json— Binds the local repository to the board UUID, list columns, and default agent provider.AGENTS.md— Codified operational rules for autonomous agents (Cursor, Claude Code, Antigravity, etc.) so they know when to claim tasks, ask clarifying questions, log progress, and submit work for human testing.
🛠️ Available MCP Tools
Agents have access to these purpose-built lifecycle tools:
| Tool | Purpose |
| :--- | :--- |
| agilemonster_get_context | Inspects board, columns, and active tasks. Auto-detects project from .agilemonster.json or directory name. |
| agilemonster_init_project | Binds current repo to an Agile Monster board and creates AGENTS.md. |
| agilemonster_list_my_tasks | Lists cards assigned to the AI agent (queued, in_progress, waiting_for_input, review). |
| agilemonster_claim_task | Claims a task, marking it in_progress on the board before code edits start. |
| agilemonster_ask_question | Posts a question comment on the card and marks status as waiting_for_input so the user is alerted. |
| agilemonster_add_progress | Logs implementation progress notes to task comments. |
| agilemonster_submit_for_review | Marks work complete, moves card to Review column, reassigns to human member for confirmation, and posts test instructions. |
| agilemonster_create_followup_tasks | Creates follow-up cards (e.g. "Deploy to Test", "Deploy to Production", "Write integration tests"). |
| agilemonster_get_deploy_profile | How this project deploys: route, exact command, confidence, the evidence behind it, alternatives, and recent outcomes. |
| agilemonster_record_deployment | Records how a deployment went (or pins the route the user stated) so every later task deploys the same proven way. |
🧠 Who works a card that is queued from the board
A card you assign to an agent in the web app is picked up by the background runner on your machine.
The background runner
bootstrap installs the runner as a service that starts with the computer, so cards are worked whether or
not a coding tool is open. Without it, cards are only picked up while an AI coding tool with this MCP server
is open in the project folder.
npx -y @agilemonster/mcp-server service status # is it installed and running?
npx -y @agilemonster/mcp-server service install # install or repair it
npx -y @agilemonster/mcp-server service uninstall # stop and remove it- macOS: a launchd agent (
~/Library/LaunchAgents/com.agilemonster.pulse.plist). Linux: a systemd user unit (agilemonster-runner.service). Windows: not available as a service yet; keep your coding tool open, or runnpx -y @agilemonster/mcp-server pulse-daemonin a terminal. - The service runs its own copy of this package from
~/.agilemonster/runnerand keeps it up to date. - A runner that was set up by hand is left alone unless you pass
--force. - One worker per computer. While the background runner is running it alone works the cards, and the MCP server inside an open coding tool leaves them to it. A coding tool keeps its MCP server for as long as it stays open, on the version it started with, so the board does not hand cards to one that is older than the version cards need (1.0.33 today): the card then says to restart the coding tool or install the service.
- The board shows the result: next to a waiting card it says whether a computer is connected, whether it is there right now, and which agent will do the work.
The agent that does the work
The runner hands a card to a real coding agent running headless in the project folder — the same agent you use in the IDE, with the same ability to search the code, open what it finds, run the build and fix what it broke:
| Card's agent | Command line agent used | One-time setup |
| :--- | :--- | :--- |
| Cursor | cursor-agent -p --force | curl https://cursor.com/install -fsS \| bash, then cursor-agent login |
| Claude Code | claude -p --permission-mode acceptEdits --allowedTools Bash | npm install -g @anthropic-ai/claude-code, then claude auth login |
| Codex | codex exec --sandbox workspace-write | npm install -g @openai/codex, then codex login |
If a terminal answers "command not found" for one of these, the agent is installed somewhere that terminal
does not search. npx -y @agilemonster/mcp-server agents login finds it wherever it is, and the board shows
the sign-in command with its full path.
The runner also finds an agent that is not on your PATH — for example the Codex CLI that the Codex app and
its IDE plugin install, already signed in with your ChatGPT account — so there is often nothing to set up.
Nothing stands in silently. A card assigned to an agent by name is done by that agent or it waits, and the card says what it is waiting for (usually one sign-in command). A card set to Automatic is done by whichever agent is ready. Why a sign-in at all: an IDE's chat window only acts when you type into it, so unattended work goes through that product's command line agent, which signs in separately from the IDE. An IDE without a command line agent (Antigravity, Windsurf) only works a card from its own chat window. Cards assigned before 1.0.28 keep the old behaviour (any ready agent may do them).
To see what this machine will use, and the one step that would fix an agent that is not ready:
npx @agilemonster/mcp-server agentsThe agent gets the card, the requester's replies on it, and three rules: decide open details the way the codebase already does instead of asking, check your own work, and do not commit — the runner commits and deploys exactly the files the agent changed, after its own build check.
- No CLI installed or signed in? The card falls back to the built-in engine (the server-side model picks a few files and writes one patch). It cannot explore or debug, so it is noticeably weaker; the card tells you what to install or sign in to.
- Only your own cards reach the agent. It can run commands on your machine, so a card or comment written by another board member is never passed to it. Those cards use the built-in engine.
- You can keep working while a card runs. The agent does not work in your folder. It works in a private
copy of it, made in seconds next to the project (a hidden
.agilemonster-…folder, removed when the run ends), with your installed packages, local config and uncommitted work included. Only the files the agent changed are brought back and committed. Whatever you (or another agent session) edit in your own folder meanwhile stays yours: it is never committed with the card and never "put back". - Your edits are never overwritten. If the agent changed a file that you also changed while it worked, or one that already had uncommitted changes of yours, nothing of the card is put in your folder and the card asks you to commit or stash first.
- Where that copy is possible. On a disk that can clone files instantly: APFS on any Mac, Btrfs or XFS on Linux. The project folder must be the top of its own Git repository. Elsewhere (Windows, ext4, a subfolder of a larger repository) the agent works in the project folder itself, and files you save during the run can end up in the card's commit, so leave the folder alone until the card is in review.
- After a card that changes dependencies, your own folder has the new
package.json(orpubspec.yaml, …) but still the old installed packages: run your usual install command. The review says so when it applies. - How long a run may take. A run is not on a fixed clock. It ends when the agent finishes, when the agent has shown no sign of work for ten minutes, or after three hours in total. Signs of work are: anything the agent prints, Claude Code's own session transcript growing, an uncommitted file in the working folder changing, and the agent's processes (the tests or build it is waiting on included) using the processor. A command that is alive but idle, such as a dev server or a test runner in watch mode, is not work. On Windows only Claude Code can be observed this way; for the other agents only the three hour limit applies.
- A run that is stopped loses nothing. The files the agent had changed are kept for 14 days: in its private
copy, or, where it worked in the project folder itself, set aside under
~/.agilemonster/kept-workwith the folder put back the way it was. The card says exactly what was kept. Try again continues the same Claude Code session where it stopped; Cursor, Codex and your own command start again with the kept files already in place.
| Variable | Effect |
| :--- | :--- |
| AGILEMONSTER_AGENT_ENGINE | claude, cursor or codex to pin one; builtin to never start an agent CLI. |
| AGILEMONSTER_AGENT_COMMAND | Your own command instead. It runs in the project folder with the brief in $AGILEMONSTER_PROMPT_FILE; whatever it prints last is the report. |
| AGILEMONSTER_AGENT_QUIET_MINUTES | How long an agent may show no sign of work before its run is stopped (default 10; off: only the overall limit applies). |
| AGILEMONSTER_AGENT_TIMEOUT_MINUTES | The overall limit for one agent run, however busy the agent is (default 180, at most 480). |
| AGILEMONSTER_ISOLATE | off: the agent works in the project folder itself. copy: always use a private copy, even on a disk that has to copy every file (slow for a large project). Unset: a private copy wherever it is instant. |
| AGILEMONSTER_REPORT | off: the runner keeps its own failures on this computer and reports none of them (see "What the runner reports back"). Unset: failures are reported. |
What the runner reports back
When something goes wrong on your computer (a card fails, the runner crashes, an update or a deploy does not go through, or the runner cannot work the way it prefers), the background runner tells Agile Monster with its next heartbeat, so that setups that break get fixed instead of staying in a log file on your disk.
- What is sent: the name of the event (
card.failed,deploy.failed, ...), a short error message, which agent it concerned, and how often it happened. With every heartbeat: the runner version, your system (darwin, its release,arm64), the Node version, and each agent's version and whether it is ready. - What is never sent: card titles and text, project names, your code, and file paths. Of a path only the last part is kept (
…/app.ts); the home folder, e-mail addresses and anything shaped like a key or a token are removed before the message is stored, even on your own disk (~/.agilemonster/outbox.json). - Turning it off: set
AGILEMONSTER_REPORT=off. Nothing is collected and nothing is sent; cards work exactly as before.
A card that was made from a problem report or an error alert is never handed to an agent that can run commands, on any runner version: its text came from outside your board.
Connecting the right folder
bootstrap connects the folder your terminal is in. Before it writes anything it shows the folder, its repository and the board, and it stops in two cases (1.0.33 and newer):
- The folder already belongs to another board. Usually the terminal is in the wrong project. It cancels by default; in a terminal you can choose to move the folder to the new board or let both boards use it. Without a terminal, add
--moveor--both. - The folder looks nothing like the board (its name, the folder above it and its repository are compared with the board's name). It asks once; without a terminal, add
--yes.
The background runner also never rewrites a folder's .agilemonster.json to another board while the board it names still uses the folder, and the board's AI Agents settings show a warning when two boards are connected to one folder.
Whose cards reach your agents
A coding agent started by the runner (Claude Code, Cursor, Codex) can read, change and run things in your project folder. So it only works cards written by:
- you, the account this computer's API key belongs to, and
- board members you named under "Who may send requests to my agents" in the board's AI Agents & Project Setup (runner 1.0.33 and newer). The list is per board, starts empty, and only you can change it. Their replies to an agent's question reach the agent too.
Everyone else's cards are still done, by the built-in engine, which edits a handful of files in one pass and has no shell. The card says so and names who can add the requester.
The runner reads your list from the server at the start of every run, for your own account. It never takes it from a card or a comment, so nobody can add themselves, and taking someone off the list counts for the next card, including cards they wrote earlier. If the list cannot be read, only your own cards reach an agent.
Being on the list never includes choosing how the project deploys: a deploy: reply, a "yes" to a first-time deploy question, an undo, and what happens to unpushed commits are only accepted from you.
🚀 How deployment is decided (and remembered)
Cards started from the Agile Monster web app run in the background without your IDE's context, so the server works out how a project ships from evidence and from what worked before:
- Explicit —
.agilemonster/deploy.jsonin the repo ({"method": "docker_compose", "command": "...", "live_url": "..."}), or a route pinned withagilemonster_record_deployment({ pin: true })/ a card reply. - Learned — the last deployment that was verified on this machine.
- Evidence, ranked — a deploy workflow that really fires on a push to the checked-out branch (path filters and
workflow_runchains included) › a deploy script › a cloud CLI config › the Docker Compose stack that is running from this folder (reused with its exact project name and files) › a compose file › a plaingit push.
What the runner guarantees:
- Commits only the files it changed — never
git add -A; local files holding your API key are filtered and added to.git/info/exclude. - Verifies before claiming "Deployed" — deploy workflow run for that commit, container state and health, script exit code, and a smoke check of a URL you provided. A guessed URL can never fail a deploy.
- Asks once, then remembers — an unconfirmed deploy script, cloud CLI or manually-dispatched workflow is not run on a guess. Reply on the card with
deploy: <command or method>to confirm;retryre-runs only the deployment, not the code change. - Heals what it can — starts Docker Desktop/OrbStack if it is installed but stopped, rebases and re-pushes when the remote moved ahead, retries network errors, and falls back to the next route when the chosen one plainly does not apply.
- Checks the branch before it starts — fetches, and fast-forwards a folder that is only behind (Git refuses if that would touch an uncommitted edit of yours). Unpushed commits that fit are replayed on top. If unpushed commits clash with the remote, the card asks first, in plain words, instead of letting an agent work for minutes on something that cannot be pushed.
- A refused push comes with ways out — the card says what clashes (this card, or older commits that never left this computer) and offers Ship only this change or Redo on the latest version. Anything moved out of the way is kept on an
agilemonster/backup-…branch; nothing is deleted. If you push the change yourself,retryonly checks the deployment: no second commit, no second deploy. - Asks before it guesses — the agent decides how to build something by itself, but when a card names a screen or section that does not exist as written, or can be read as two different changes, it stops and asks which is meant, with the readings as buttons.
- Every change can be taken back — in review, Undo this change (or the reply
undo) reverts the card's commits with new commits and deploys again, so the product is as it was before the card. On a board that deploys on approval, it discards the change that was waiting. It refuses, and says why, when later work builds on the change or the folder has uncommitted work. - Never reports a slow pipeline as failed — a CI run that outlives the wait is marked pending and re-checked on later pulses; the outcome is posted on the card.
State lives outside your repositories: ~/.agilemonster/projects/ (per-project deployment history) and
~/.agilemonster/logs/daemon.jsonl (structured daemon log).
When the runner asks a question, the card shows the answers it accepts as buttons, so nobody has to type
these. They still work as typed replies: retry · deploy: github_actions · deploy: docker_compose · deploy: manual · deploy: ./deploy/deploy.sh · live url: https://example.com · deploy: only this change · branch: start fresh · undo
Replies that decide what runs or what moves on your computer (deploy: …, branch: start fresh) are only taken from the person whose account the runner uses.
💡 MCP Native Prompts & Resources
The server exposes Model Context Protocol Prompts and Resources so agents can automatically load operational instructions into their context:
Prompts
agilemonster_agent_protocol: System instructions explaining the full task lifecycle protocol.agilemonster_work_on_task: Guided workflow prompt for an agent to claim, investigate, implement, test, submit for review, and propose follow-up tasks for a specific card ID.
Resources
agilemonster://guidelines/agents: Live markdown text of the official Agent Guidelines (text/markdown).agilemonster://project/context: Current repository board, list structure, and active agent tasks as live JSON (application/json).
🤖 The Autonomous Agent Orchestrator CLI
Use the built-in orchestrator to monitor tasks, dispatch work, or run a background watcher:
# Check current tasks assigned to agents for this project
npx @agilemonster/mcp-server status
# Watch for newly assigned tasks in real-time
npx @agilemonster/mcp-server watch
# Claim a task
npx @agilemonster/mcp-server claim <card_id>
# Submit for user testing & confirmation
npx @agilemonster/mcp-server review <card_id> "Implemented dark mode toggle" "Test via Settings screen"
# Ask the user a question
npx @agilemonster/mcp-server question <card_id> "Should we support OAuth tokens as well?"📚 REST API Reference
For developers building custom scripts, CI/CD bots, or proprietary agent orchestrators, refer to the full REST API specification in docs/AGENT-API.md.
