aacworkflow-mcp
This MCP server lets Claude/Claude Code drive AACWorkflow with your own token, exposing 71 tools for workspace, agent, task, project, squad, autopilot, skill, runtime, and analytics operations.
Authenticate locally via stdio or remotely via hosted HTTP with Bearer token or OAuth 2.1, including multi-workspace selection.
Inspect account/workspace details, members, runtimes, and runtime usage/activity.
Manage agents: list/get/create/update/archive/restore, create from templates, and attach/detach/list skills.
Manage skills: list/get/create/update/delete/import from external sources.
Manage tasks/issues: list/get/create/update/delete/search, assign/rerun, comment, subscribe, and handle attachments.
Manage projects, labels, squads, squad members, and autopilots (create/update/delete/trigger/list runs).
Query analytics for daily usage, usage by agent, and agent runtime totals; discover capabilities/metadata and use structured outputs/errors with dry-run previews for destructive actions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@aacworkflow-mcp list my aacworkflow agents"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
aacworkflow-mcp
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)
Create a token: aacworkflow.com → your workspace → Settings → Tokens → create. Copy the
mul_…value.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-mcpStart 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>, orpass
workspace_idper call — runlist_workspacesfirst 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_tokenon 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/authorizerenders a small page asking you to paste yourmul_…token once; it's verified againstAACWORKFLOW_SERVER_URLand 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-mcpPut 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 |
| RFC 8414 metadata (issuer, |
| RFC 9728 metadata pointing MCP clients at the authorization server |
| Starts the flow; renders the token-paste consent page |
| Consent page submits here; verifies the token against AACWorkflow and redirects back with a code |
| Exchanges an authorization code (+ PKCE verifier) or refresh token for an access token |
| RFC 7591 dynamic client registration |
| 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_membersRuntimes:
list_runtimes,update_runtime,get_runtime_usage,get_runtime_activityAgents:
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_agentSkills:
list_skills,get_skill,create_skill,update_skill,delete_skill,import_skillTasks (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_attachmentProjects / labels:
list_projects,create_project,update_project,delete_project,list_labels,create_label,update_label,delete_labelSquads:
list_squads,get_squad,create_squad,update_squad,delete_squad,list_squad_members,add_squad_member,remove_squad_memberAutopilots:
list_autopilots,get_autopilot,create_autopilot,update_autopilot,delete_autopilot,trigger_autopilot,list_autopilot_runsAnalytics:
dashboard_usage_daily,dashboard_usage_by_agent,dashboard_agent_runtimeDiscovery:
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_issuewithassignee_type:"agent"+assignee_id, orassign_issue_to_agenton 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 inspectingOPTIONSallowed-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_autopilotneedtitlenotname;create_squadneedsleader_idnotleader;update_runtime/update_autopilotarePATCHnotPUT; squad member add/remove use{member_type, member_id}and a body-basedDELETErather 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 isPOST .../subscribewith{subscribed: true|false}, not REST verbs on.../subscribers; a documented.../issues/:id/runsendpoint doesn't exist (removed); andassignee_typeisagent | member | squad— neveruser. 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 | |
| — | required ( |
|
| self-hosted? point here |
| — | optional default workspace |
HTTP (hosted, src/http.ts)
Env | Default | |
|
| listen port |
|
| upstream AACWorkflow API |
|
| set this in production — the public origin clients reach you at; OAuth issuer/redirect/metadata URLs are derived from it |
| — | encrypted OAuth state file on a persistent volume; set together with the key |
| — | stable 64-character hexadecimal encryption key, supplied through secret settings |
Operations
Rate limiting:
/mcpis 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
403when 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/SIGINTclose 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:watchCI (.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 toolsadd_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
Scored across 69 tools
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.
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.
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.
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
Related MCP Connectors
Your Aurentia workspace — projects, CRM, tasks, deliverables — in Claude, Cursor or any MCP client.
Create Tasks and run Workflows in Bleep from Claude, ChatGPT, and other AI assistants.
Create projects, nodes, and tasks in UluP Spaces by conversation with Claude.
Deploy, monitor, and manage your OpenClaw AI assistants via natural language.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI-native task and project management through natural language conversation with Claude, eliminating app-switching by letting you add actions, manage projects across multiple areas of focus, and maintain a GTD-style execution system directly in chat.1-
- AlicenseBqualityDmaintenanceEnables Claude to interact with Things 3 task management, allowing natural language task creation, project analysis, and GTD workflow automation.2470 PyPI44MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants like Claude to create and manage projects, todos, priorities, and statuses through natural language, bridging the gap between AI and project management workflows.-
- AlicenseCqualityDmaintenanceEnables interaction with Asana through natural language, supporting task and project management via MCP clients like Claude.26MIT