AnyForge MCP Server

Drive AnyForge from Claude CLI (Claude Code), Cursor, and other MCP clients: view and approve HIL notifications, read programs / initiatives / work items, add and modify work items, see crew outputs, and interact with crews.

The server is a thin client over AnyForge's key-authenticated control API (/api/v1/control/*). It holds no business logic and never needs a Firebase login.

User-facing setup guide: Drive AnyForge from Claude CLI (apps/www/content/docs/mcp-server.md). This README is the in-repo developer reference; the docs page is the canonical install walkthrough.

1. Authorise this machine (once)

npx @anyforge/control init

This runs the device-auth flow and writes a long-lived sk_anyforge_… key to ~/.anyforge/credentials. The MCP server reads that file — so you don't put any secret in your MCP config.

The key carries scopes (read / write / approve). A read-only key can list and inspect but can't create work items or approve HILs.

2. Register with Claude CLI

claude mcp add anyforge -- npx tsx /ABS/PATH/TO/packages/control/mcp-server/index.ts

• Add --scope user to make it available in every project, or --scope project to commit it to this repo's .mcp.json.
• No env vars are required — credentials come from ~/.anyforge/credentials.

To point at a non-prod deployment or inline a key instead of using the credentials file, pass env vars:

claude mcp add anyforge \
  -e ANYFORGE_API_URL=https://staging.anyforge.ai \
  -e ANYFORGE_API_TOKEN=sk_anyforge_xxx \
  -- npx tsx /ABS/PATH/TO/packages/control/mcp-server/index.ts

Cursor / other clients

Use the equivalent stdio MCP config (command: npx, args: ["tsx", "…/index.ts"]). The same credential resolution applies.

Tools

| Tool | Scope | Description | |------|-------|-------------| | anyforge_list_pending_approvals | read | List HIL approvals awaiting a decision | | anyforge_get_approval_detail | read | Read one approval's plan / ADR / security context | | anyforge_submit_approval | approve | Approve or reject a HIL (resumes the crew) | | anyforge_list_programs | read | List programs | | anyforge_get_program | read | Get a program | | anyforge_list_initiatives | read | List initiatives with progress + spend | | anyforge_get_initiative | read | Initiative + crews + burn-down | | anyforge_approve_backlog | approve | Approve a proposed backlog (HIL #1) | | anyforge_approve_task_proposal | approve | Approve a mid-flight task proposal | | anyforge_list_work_items | read | List backlog items + crew state | | anyforge_get_work_item | read | Get one work item | | anyforge_create_work_item | write | Create a work item | | anyforge_update_work_item | write | Edit / advance / dispatch / archive / close | | anyforge_get_crew | read | Crew state + recent outputs + comments | | anyforge_post_crew_comment | write | Comment on / @-mention in a crew | | anyforge_resume_crew | approve | Resume a PAUSED/HALTED crew | | anyforge_halt_crew | approve | Halt a crew | | anyforge_amend_crew | approve | Continue & finish — send a crew at its HIL gate back to the engineer with guidance | | anyforge_create_program | write | Create a program (cross-initiative grouping) | | anyforge_write_program_brief | write | Write/update a program's brief (charter) — seeds each initiative's architect context | | anyforge_create_initiative | write | Create a (DRAFT) initiative, optionally under a program | | anyforge_dispatch_architect | write | Decompose an initiative into a backlog (→ HIL #1) | | anyforge_list_repo_index | read | List the org repo index (activity, coverage, analyzed) — discover codebases to scope | | anyforge_get_repo_analysis | read | One repo's coverage / architecture / gap summary | | anyforge_analyze_repos | write | Start Phase-1 analysis for one or more repos | | anyforge_start_coverage_sweep | write | Paced Phase 1→2 analysis sweep over a program/repo set | | anyforge_refresh_repo_index | write | Refresh the repo index + committed-coverage detection now |

Prompts (guided flows)

MCP clients that support server prompts (e.g. Claude Code surfaces them as /mcp__anyforge__<name> slash commands) get:

| Prompt | Args | What it does | |--------|------|--------------| | genesis | programId?, goal? | Turns the client into the Program Genesis agent: it interviews you to scope a program across your codebases (using anyforge_list_repo_index / anyforge_get_repo_analysis), writes the program brief, then creates one initiative per in-scope codebase and offers to dispatch the architect on each. |

The Genesis flow runs entirely in your agent — there's no server-side chat-in-a-tool. The prompt gives your client the persona + interview script; it drives the conversation and calls the tools above as it goes.

Example prompts

• "What's waiting for my approval in AnyForge?" → anyforge_list_pending_approvals
• "Show me the plan for approval abc123 then approve it." → anyforge_get_approval_detail → anyforge_submit_approval
• "Add a P1 bug: rate-limit the export endpoint." → anyforge_create_work_item
• "What did crew xyz produce? Post a comment asking it to add tests." → anyforge_get_crew → anyforge_post_crew_comment
• "Scope a coverage program across our Go services." → run the genesis prompt → it lists repos, scopes, and creates an initiative per service.

How it works

Claude CLI ──stdio──▶ MCP server ──HTTPS (Bearer sk_anyforge_…)──▶ /api/v1/control/* ──▶ shared control services

The /api/v1/control/* routes share the exact same service layer as the AnyForge web app, so the CLI and the dashboard behave identically.

Build & publish (maintainers)

The package ships compiled JS (dist/), so end users can run npx -y @anyforge/mcp-server without a TypeScript toolchain. Source lives in index.ts / lib/ / tools/; tsc emits dist/ (shebang preserved, .js import specifiers already in source for NodeNext).

npm install          # includes the typescript devDependency
npm run build        # tsc → dist/
npm pack --dry-run   # verify the tarball: dist/ + README + package.json only

Publishing is automated. Push a mcp-server-v<version> tag and the .github/workflows/publish-mcp-server.yml workflow builds and runs npm publish (scoped public). Keep the tag version in sync with package.json:

cd packages/control/mcp-server
npm version patch          # bumps package.json, e.g. 2.0.0 → 2.0.1
git commit -am "chore(mcp): release mcp-server vX.Y.Z"   # if not committed by npm version
git tag mcp-server-v$(node -p "require('./package.json').version")
git push origin main --tags

The workflow needs an NPM_TOKEN repo secret (an npm automation token for an account with publish rights on the @anyforge scope). One- time setup: npm token create --read-only=false, then add it under GitHub → Settings → Secrets → Actions as NPM_TOKEN.

To publish manually instead: npm login && npm publish from this directory (prepublishOnly rebuilds dist/ first).