aacworkflow-mcp

MCP server that lets Claude and Claude Code drive AACWorkflow: tasks (issues), agents, projects, squads, autopilots and analytics.

Bring your own token. Every user runs their own copy with their own AACWorkflow token — there is no shared server and no central credential store. Your token scopes you to the workspaces (companies) you belong to, and you can drive several from one install.

Quick start (any AACWorkflow user)

1. Create a token: aacworkflow.com → your workspace → Settings → Tokens → create. Copy the mul_… value.

2. Connect it to Claude Code (no clone needed — runs straight from GitHub):

   claude mcp add aacworkflow --scope user \
     -e AACWORKFLOW_TOKEN=mul_your_token \
     -- npx -y github:AAChibilyaev/aacworkflow-mcp

3. Start a new Claude Code session and ask: "list my aacworkflow agents", "create a task and assign it to the Маркетолог agent", "show this week's usage".

Multiple companies / workspaces

If your token belongs to one workspace it is used automatically. If you belong to several, either:

• set a default: add -e AACWORKFLOW_WORKSPACE_ID=<id>, or

• pass workspace_id per call — run list_workspaces first to see the ids.

Related MCP server: Things 3 MCP Server

Remote / hosted — work from anywhere (Claude Code, claude.ai, ChatGPT)

The same code also runs as a hosted, multi-tenant HTTP endpoint. Host it once; any registered AACWorkflow user connects with their own token and drives their own workspaces (companies). No shared credentials.

Two ways to authenticate against the hosted endpoint — pick whichever your client supports:

• Direct bearer token — put Authorization: Bearer mul_your_token on the request. No handshake, works with any HTTP MCP client (Claude Code, curl, Claude Desktop's remote config).

• OAuth 2.1 — the server is a full authorization server (dynamic client registration, authorization_code + PKCE, refresh tokens, revocation, RFC 8414 / RFC 9728 metadata). Required by clients that only support OAuth discovery, like claude.ai and ChatGPT connectors. There's no separate AACWorkflow login page to redirect to, so /authorize renders a small page asking you to paste your mul_… token once; it's verified against AACWORKFLOW_SERVER_URL and exchanged for an opaque, short-lived, revocable access token — the raw token itself is never handed to the connecting app.

Run the server

# from source
npm install && npm run build
PORT=8787 AACWORKFLOW_MCP_PUBLIC_URL=https://mcp.example.com npm run start:http
# or Docker
docker build -t aacworkflow-mcp . && docker run -p 8787:8787 \
  -e AACWORKFLOW_MCP_PUBLIC_URL=https://mcp.example.com aacworkflow-mcp

Put it behind HTTPS (any reverse proxy / Coolify / Cloudflare) → e.g. https://mcp.example.com/mcp. Set AACWORKFLOW_MCP_PUBLIC_URL to that exact public origin — OAuth issuer/redirect URLs are derived from it and must match what clients actually reach (OAuth requires HTTPS in production; http://localhost / http://127.0.0.1 are allowed for local testing).

Endpoints: POST/GET/DELETE /mcp (MCP Streamable HTTP), GET /health, plus the OAuth set below.

Connect from Claude Code (remote)

claude mcp add aacworkflow --transport http https://mcp.example.com/mcp \
  --header "Authorization: Bearer mul_your_token"

Connect from claude.ai / ChatGPT (OAuth connector)

Settings → Connectors → Add custom connector → MCP server URL https://mcp.example.com/mcp. Leave auth as OAuth (default) — the client discovers /.well-known/oauth-protected-resource/mcp, registers itself, and opens /authorize in a browser tab where you paste your AACWorkflow token once. From then on the connector holds its own rotating access/refresh tokens.

If your connector only supports static bearer tokens, you can still skip OAuth entirely and use Authorization: Bearer mul_your_token directly, same as the Claude Code example above.

OAuth endpoints

Tokens are in-memory only (opaque aacmcp_at_… / aacmcp_rt_…, 1h access / rotating refresh) — restarting the process ends all OAuth sessions; clients re-run the flow automatically. This is intentional for a single-instance deployment; there is no cross-instance token store.

Marketplace / directory listing

The hosted endpoint now satisfies the OAuth 2.1 requirement for the Anthropic Connectors directory / OpenAI Apps. Actually publishing still requires a vendor review submitted from your own org account — that's a business step, not a code change.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aacworkflow": {
      "command": "npx",
      "args": ["-y", "github:AAChibilyaev/aacworkflow-mcp"],
      "env": { "AACWORKFLOW_TOKEN": "mul_your_token" }
    }
  }
}

Restart Claude Desktop.

Local install (development)

git clone https://github.com/AAChibilyaev/aacworkflow-mcp
cd aacworkflow-mcp && npm install && npm run build
claude mcp add aacworkflow -e AACWORKFLOW_TOKEN=mul_xxx -- node "$PWD/dist/index.js"

Tools (69)

• Account/workspace: whoami, list_workspaces, get_workspace, update_workspace, list_members

• Runtimes: list_runtimes, update_runtime, get_runtime_usage, get_runtime_activity

• Agents: list_agents, get_agent, create_agent, update_agent, archive_agent, restore_agent, list_agent_templates, create_agent_from_template, list_agent_tasks, list_agent_skills, attach_skill_to_agent, detach_skill_from_agent

• Skills: list_skills, get_skill, create_skill, update_skill, delete_skill, import_skill

• Tasks (issues): list_issues, get_issue, create_issue, update_issue, delete_issue, assign_issue_to_agent, rerun_issue, comment_issue, list_comments, search_issues, list_issue_subscribers, subscribe_to_issue, unsubscribe_from_issue, list_issue_attachments, get_attachment, delete_attachment

• Projects / labels: list_projects, create_project, update_project, delete_project, list_labels, create_label, update_label, delete_label

• Squads: list_squads, get_squad, create_squad, update_squad, delete_squad, list_squad_members, add_squad_member, remove_squad_member

• Autopilots: list_autopilots, get_autopilot, create_autopilot, update_autopilot, delete_autopilot, trigger_autopilot, list_autopilot_runs

• Analytics: dashboard_usage_daily, dashboard_usage_by_agent, dashboard_agent_runtime

Dispatch work to an agent: create_issue with assignee_type:"agent" + assignee_id, or assign_issue_to_agent on an existing issue — the agent's runtime daemon picks it up and runs it.

Endpoint provenance: AACWorkflow doesn't publish an OpenAPI/Swagger spec. Every tool listed above has been exercised against the live API (https://aacworkflow.com) with a real token — read-only tools by calling them directly, mutating ones by inspecting OPTIONS allowed-methods and validation-error messages (e.g. a missing required field 400s with its name) rather than by guessing. That pass caught and fixed several real bugs versus the original CLI-based guesses: create_project/create_autopilot need title not name; create_squad needs leader_id not leader; update_runtime/update_autopilot are PATCH not PUT; squad member add/remove use {member_type, member_id} and a body-based DELETE rather than a nested path; agent↔skill attach/detach is a read-then-PUT-the-full-list operation, not per-skill POST/DELETE; issue subscribe/unsubscribe is POST .../subscribe with {subscribed: true|false}, not REST verbs on .../subscribers; and a documented .../issues/:id/runs endpoint doesn't exist (removed). If something still 404s on your instance, open an issue with the correct path.

Config

stdio (local, src/index.ts)

HTTP (hosted, src/http.ts)

Operations

• Rate limiting: /mcp is capped at 120 req/min per IP; the OAuth endpoints (/authorize, /token, /register, /revoke) have their own stricter limits built into the SDK's auth router.

• Logging: one structured JSON line per request to stdout (method, path, status, latency, session id) — no tokens are ever logged; OAuth token log lines carry only an 8-char prefix for correlation.

• Session lifecycle: idle MCP sessions (no request for 30 minutes) are reaped every 5 minutes to bound memory; SIGTERM/SIGINT drain in-flight sessions and OAuth state before exiting.

• Scaling: session and OAuth-token state is in-process memory, sized for a single instance (which is what a Coolify/Cloudflare deployment of this project is). Running multiple replicas needs sticky sessions in front — there's no shared session/token store.

Development

npm install
npm run build     # tsc
npm test          # vitest — server tools, OAuth provider, HTTP app smoke tests
npm run test:watch

CI (.github/workflows/ci.yml) runs build + test + a Docker build on every push/PR to main.

Security

Your token is read only from the environment you pass at install time (stdio) or from the Authorization header per-request (HTTP), and sent only to your AACWORKFLOW_SERVER_URL over HTTPS. It is never written to the repo, logged, or shared. Revoke it anytime in Settings → Tokens.

For the hosted HTTP transport, OAuth access/refresh tokens are opaque, scoped to the client that requested them, expire in an hour (access) or are revoked individually (refresh, rotated on every use) — they carry no information about your underlying AACWorkflow token beyond an in-memory mapping on this server.

MIT licensed.