Skip to main content
Glama

aacworkflow-mcp

CI

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

Bring your own token. Local installs use your personal AACWorkflow token. The hosted endpoint keeps each connecting user's credentials separate and can persist OAuth credentials in encrypted storage. 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

Endpoint

Purpose

GET /.well-known/oauth-authorization-server

RFC 8414 metadata (issuer, /authorize, /token, /register, /revoke)

GET /.well-known/oauth-protected-resource/mcp

RFC 9728 metadata pointing MCP clients at the authorization server

GET/POST /authorize

Starts the flow; renders the token-paste consent page

POST /authorize/verify

Consent page submits here; verifies the token against AACWorkflow and redirects back with a code

POST /token

Exchanges an authorization code (+ PKCE verifier) or refresh token for an access token

POST /register

RFC 7591 dynamic client registration

POST /revoke

RFC 7009 token revocation

Tokens are opaque (aacmcp_at_… / aacmcp_rt_…, 1h access / rotating refresh). For hosted deployments, configure AACWORKFLOW_MCP_STATE_FILE on a persistent volume and AACWORKFLOW_MCP_STATE_KEY as a stable 64-character hexadecimal encryption key in the hosting platform's secret settings. Registered clients and issued tokens then survive process restarts. The state file is AES-256-GCM encrypted and written atomically with mode 0600; unreadable, corrupted, or incorrectly encrypted state prevents startup rather than silently invalidating existing credentials. A failed write disables authorization and makes /health return 503; repair storage and restart the process to resume using the last saved state.

For example, mount a volume at /data/oauth writable by the container's node user (uid 1000), set AACWORKFLOW_MCP_STATE_FILE=/data/oauth/state.enc, and generate the key with openssl rand -hex 32. Keep the key unchanged across redeploys and back up the volume together with its key using your normal secret-backup process. Do not commit the key or include it in logs. A single server process must own the file; this is not a shared store for multiple replicas.

Without these two settings, OAuth state remains ephemeral for backward compatibility. Previously lost credentials cannot be reconstructed: an already disconnected client needs one new authorization after persistence is enabled. Pending browser authorization transactions, authorization codes, and MCP transport sessions remain in memory; clients can initialize a new transport after a restart using their retained credentials.

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 (71)

  • 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

  • Discovery: get_capabilities (feature flags, incl. what's deliberately not implemented), get_metadata (every enum the schemas below use — statuses, priorities, assignee/execution modes, error codes)

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; a documented .../issues/:id/runs endpoint doesn't exist (removed); and assignee_type is agent | member | squad — never user. If something still 404s on your instance, open an issue with the correct path.

Agent contract (annotations, schemas, structured output)

Every tool declares MCP ToolAnnotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint) so a client can judge risk before calling — e.g. import_skill is openWorldHint: true (fetches an external URL), delete_issue is destructiveHint: true. Every update_* tool takes field-level Zod schemas, not patch: Record<string, any>. Every tool has a real outputSchema and returns structuredContent (plus a JSON-text fallback in content), so a client can chain create_issue → issue.id → assign_issue_to_agent without parsing text. All destructive tools accept dry_run: true to preview the resource instead of deleting it. workspace_id is required on every write tool (optional, best-effort-resolved on reads) — the server never guesses which of your workspaces to mutate. Errors are structured {code, message, retryable, retry_after_ms?} with code one of NOT_FOUND | UNAUTHORIZED | FORBIDDEN | INVALID_ARGUMENT | CONFLICT | RATE_LIMITED | TIMEOUT | INTERNAL_ERROR. The server also sets MCP instructions describing the Workspace → Project → Squad → Agent → Issue model, so a client doesn't need that re-explained per chat.

Deliberately not implemented (see get_capabilities.excluded_by_design): per-tool OAuth scopes, and a first-class Run API (list_runs/pause_run/...). AACWorkflow's own tokens have no scope system server-side and its API has no run-level pause/resume/retry endpoints — either would be decorative, not enforced, if bolted onto this MCP layer alone. list_agent_tasks / rerun_issue expose what's really there instead.

Config

stdio (local, src/index.ts)

Env

Default

AACWORKFLOW_TOKEN

—

required (mul_…)

AACWORKFLOW_SERVER_URL

https://aacworkflow.com

self-hosted? point here

AACWORKFLOW_WORKSPACE_ID

—

optional default workspace

HTTP (hosted, src/http.ts)

Env

Default

PORT

8787

listen port

AACWORKFLOW_SERVER_URL

https://aacworkflow.com

upstream AACWorkflow API

AACWORKFLOW_MCP_PUBLIC_URL

http://127.0.0.1:$PORT

set this in production — the public origin clients reach you at; OAuth issuer/redirect/metadata URLs are derived from it

AACWORKFLOW_MCP_STATE_FILE

—

encrypted OAuth state file on a persistent volume; set together with the key

AACWORKFLOW_MCP_STATE_KEY

—

stable 64-character hexadecimal encryption key, supplied through secret settings

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.

  • Session identity: a transport session belongs to its OAuth client and underlying AACWorkflow identity. Other authenticated callers receive 403 when attempting to use, stream, or delete that session; rotating the owner's OAuth access token preserves access.

  • Refresh scopes: refresh requests can retain or narrow their original grant; expansion is rejected before consuming the refresh token.

  • 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 close transport sessions. Configured OAuth state is saved on each client registration, token issue/rotation/revocation, and access-token expiration.

  • Scaling: transport sessions remain in-process; the optional encrypted OAuth file has one process owner. Multiple replicas require a shared store and coordinated session routing.

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.

Available Tools

69 tools
add_squad_memberC

Add an agent to a squad.

Inputs: id (required), agent_id (required), workspace_id.

archive_agentA

Archive an agent (soft-delete; it stops picking up new work).

Inputs: id (required), workspace_id.

assign_issue_to_agentA

Assign an existing issue to an agent (dispatches the task).

Inputs: id (required), agent_id (required), workspace_id.

attach_skill_to_agentC

Attach a skill to an agent.

Inputs: id (required), skill_id (required), workspace_id.

comment_issueC

Add a comment to an issue.

Inputs: id (required), body (required), workspace_id.

create_agentC

Create an agent on a runtime. Use visibility 'workspace' so all members can use it.

Inputs: name (required), runtime_id (required), model, visibility, +4 more.

create_agent_from_templateB

Create an agent from a template slug.

Inputs: slug (required), runtime_id (required), name, visibility, +1 more.

create_autopilotB

Create an autopilot — a recurring/triggered automation that files an issue for an agent.

Inputs: title (required), assignee_id (required), assignee_type (required), execution_mode (required), +4 more.

create_issueC

Create a task. Dispatch to an agent with assignee_type='agent' + assignee_id.

Inputs: title (required), status, due_date, priority, +6 more.

create_labelC

Create an issue label.

Inputs: name (required), color, workspace_id.

create_projectC

Create a project.

Inputs: title (required), description, workspace_id.

create_skillC

Create a skill.

Inputs: name (required), content, description, workspace_id.

create_squadD

Create a squad.

Inputs: name (required), leader_id (required), description, workspace_id.

dashboard_agent_runtimeD

Agent run-time totals.

Inputs: workspace_id.

dashboard_usage_by_agentD

Usage by agent.

Inputs: workspace_id.

dashboard_usage_dailyC

Daily credit/token usage.

Inputs: workspace_id.

delete_attachmentC

Delete an attachment.

Inputs: id (required), workspace_id.

delete_autopilotC

Delete an autopilot.

Inputs: id (required), workspace_id.

delete_issueA

Delete an issue. Immediately clears its comments, reactions, and attachments — cannot be undone.

Inputs: id (required), workspace_id.

delete_labelC

Delete an issue label.

Inputs: id (required), workspace_id.

delete_projectC

Delete a project.

Inputs: id (required), workspace_id.

delete_skillC

Delete a skill.

Inputs: id (required), workspace_id.

delete_squadA

Archive (soft-delete) a squad; assigned issues transfer to its leader.

Inputs: id (required), workspace_id.

detach_skill_from_agentB

Detach a skill from an agent.

Inputs: id (required), skill_id (required), workspace_id.

get_agentC

Get full details of one agent.

Inputs: id (required), workspace_id.

get_attachmentA

Get an attachment's metadata (including its download URL).

Inputs: id (required), workspace_id.

get_autopilotC

Get one autopilot.

Inputs: id (required), workspace_id.

get_issueB

Get one issue (task) with full detail.

Inputs: id (required), workspace_id.

get_runtime_activityC

Activity log for one runtime.

Inputs: id (required), workspace_id.

get_runtime_usageC

Resource consumption metrics for one runtime.

Inputs: id (required), workspace_id.

get_skillC

Get one skill's details.

Inputs: id (required), workspace_id.

get_squadB

Get one squad with its members.

Inputs: id (required), workspace_id.

get_workspaceA

Get one workspace's details.

Inputs: id (required).

import_skillA

Import a skill from GitHub, ClawHub, or another source URL.

Inputs: source (required), workspace_id.

list_agentsB

List agents in the workspace.

Inputs: workspace_id.

list_agent_skillsB

List skills attached to an agent.

Inputs: id (required), workspace_id.

list_agent_tasksC

List tasks an agent has worked on.

Inputs: id (required), workspace_id.

list_agent_templatesA

List built-in agent template slugs.

Inputs: workspace_id.

list_autopilot_runsB

List runs of an autopilot.

Inputs: id (required), workspace_id.

list_autopilotsA

List autopilots (scheduled/triggered automations).

Inputs: workspace_id.

list_commentsB

List comments on an issue.

Inputs: id (required), workspace_id.

list_issue_attachmentsB

List attachments on an issue.

Inputs: id (required), workspace_id.

list_issuesB

List issues (tasks). Filter by status / assignee / project.

Inputs: status, project_id, assignee_id, workspace_id, +1 more.

list_issue_subscribersB

List subscribers on an issue.

Inputs: id (required), workspace_id.

list_labelsB

List issue labels.

Inputs: workspace_id.

list_membersB

List members of a workspace.

Inputs: workspace_id.

list_projectsA

List projects in the workspace.

Inputs: workspace_id.

list_runtimesA

List agent runtimes (machines) in the workspace.

Inputs: workspace_id.

list_skillsA

List skills available in the workspace.

Inputs: workspace_id.

list_squad_membersC

List a squad's members.

Inputs: id (required), workspace_id.

list_squadsB

List squads (teams).

Inputs: workspace_id.

list_workspacesA

List the workspaces (companies) this token can access.

Inputs: no named parameters.

remove_squad_memberC

Remove a member from a squad.

Inputs: id (required), agent_id (required), workspace_id.

rerun_issueC

Re-run an issue's agent task.

Inputs: id (required), workspace_id.

restore_agentB

Restore a previously archived agent.

Inputs: id (required), workspace_id.

search_issuesC

Full-text search issues.

Inputs: q (required), workspace_id.

subscribe_to_issueB

Subscribe to an issue's notifications.

Inputs: id (required), workspace_id.

trigger_autopilotC

Manually trigger an autopilot run.

Inputs: id (required), workspace_id.

unsubscribe_from_issueC

Unsubscribe from an issue's notifications.

Inputs: id (required), workspace_id.

update_agentC

Update an agent.

Inputs: id (required), patch (required), workspace_id.

update_autopilotD

Update an autopilot.

Inputs: id (required), patch (required), workspace_id.

update_issueC

Update an issue.

Inputs: id (required), patch (required), workspace_id.

update_labelC

Update an issue label.

Inputs: id (required), patch (required), workspace_id.

update_projectC

Update a project.

Inputs: id (required), patch (required), workspace_id.

update_runtimeC

Update a runtime's configuration.

Inputs: id (required), patch (required), workspace_id.

update_skillD

Update a skill.

Inputs: id (required), patch (required), workspace_id.

update_squadC

Update a squad's properties.

Inputs: id (required), patch (required), workspace_id.

update_workspaceB

Update a workspace's name, description, context, or issue prefix.

Inputs: id (required), patch (required).

whoamiA

Get the authenticated user/account for the current token.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.6/5.0

    Scored across 69 tools

    Disambiguation4/5

    Most tools follow a clear CRUD pattern per resource (squad, agent, issue, project, label, skill, autopilot). A few potential overlaps exist (create_agent vs create_agent_from_template, list_members vs list_squad_members) but descriptions clarify them.

    Naming Consistency4/5

    The vast majority use verb_noun snake_case (create_squad, delete_issue). Minor exceptions like whoami and dashboard_* prefix are acceptable, and the pattern is predictable.

    Tool Count1/5

    69 tools is far beyond the typical range and even the relaxed threshold of 25+. While the server covers many domains, the sheer size makes it unwieldy for an agent to navigate and would benefit from modularization.

    Completeness4/5

    The toolset provides full CRUD for most resources and adds workflows (assign, rerun, comment, subscribe, attach). Missing administrative operations like create/delete workspace or runtime are likely out of scope, so coverage is strong.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers