@armanage/armanage-platform-mcp

External stdio MCP server for managing an Armanage company without installing or running the Armanage client. It uses an Armanage company token and exposes tools for projects, agents, teams, workflows, routines, skills, MCP resources, LLM providers, users, workloads, tasks, chats, attachments, and notifications.

This server is intentionally separate from the built-in armanage-mcp shipped inside @armanage/clarmanage:

• armanage-platform-mcp is for an external/local AI agent that configures the platform;
• the built-in client MCP is for an already registered Armanage agent executing tasks, chat routines, heartbeats, and local worktree operations.

Requirements

• Node.js 20 or newer.
• An Armanage company token created in Company → Tokens.
• The token role must have the permissions required by the requested operations.

The Rails API is the authorization boundary. The MCP server does not cache or recreate permission rules: every tool call uses Authorization: Bearer <company-token>, so role permission changes and token revocation take effect immediately.

MCP configuration

Use npx from any MCP-compatible local agent:

{
  "mcpServers": {
    "armanage-platform": {
      "command": "npx",
      "args": ["-y", "@armanage/armanage-platform-mcp"],
      "env": {
        "ARMANAGE_TOKEN": "arm_your_company_token",
        "ARMANAGE_BASE_URL": "https://beta.armanage.com"
      }
    }
  }
}

For local Armanage development, set ARMANAGE_BASE_URL to http://localhost:3000.

The token may also be passed as --token, but environment configuration is preferred because it keeps the secret out of process arguments:

ARMANAGE_TOKEN=arm_your_company_token npx -y @armanage/armanage-platform-mcp

Recommended agent instruction

Use the armanage-platform MCP to configure my Armanage company.
First call get_platform_context and inspect existing projects, agents, teams,
workflows, routines, skills, MCP resources, providers, and workloads before
creating anything. Reuse existing resources when they match. Ask me when a
name, executor, model, repository, or assignment is ambiguous. Do not delete
anything unless I explicitly request deletion.

Tool groups

• Context: get_platform_context, list_agent_configuration_catalog.
• Projects: list/get/create/update/delete, including board columns, priorities, task types, and repositories.
• Agents: list/get/create/update/delete, including team, skill, workflow, routine, model, provider, and workload assignments.
• Teams: list/get/create/update/delete, including project, agent, and user assignments.
• Configuration: company users, workloads, skills, workflows, routines, Armanage MCP resources, and LLM providers.
• Tasks: list_tasks, get_task, create_task, update_task, move_task, get_project_board.
• Chats: list_chats, get_chat, create_chat, create_direct_chat, list_chat_participants, update_chat_participants.
• Threads/messages: list_chat_threads, get_chat_thread, create_chat_thread, list_chat_messages, send_chat_message.
• Attachments: upload_file.
• Notifications: list_notifications, get_unread_notification_count.
• Execution traces: list_agent_traces, list_task_traces, get_agent_trace.

There are 67 tools in total. The API checks the token role on each request; tools are registered regardless of the role, and unauthorized calls return tool errors.

Execution traces

Use list_agent_traces with agent_id for runs across all routines (including runs without a task), or list_task_traces with project_id and task_id for runs from every agent on a task. Both return traces, total_count, and next_before_id. Pass the cursor as before_id for the next page of 20 runs.

Use a listed run's agent_id and id as agent_id and trace_id in get_agent_trace. The response contains trace: run metadata, the model/harness/configuration snapshot, recorded events, and next_after_sequence. Events are ordered by sequence. The default page has 20 events; event_limit accepts 1–100. Pass next_after_sequence as after_sequence until null to read the complete run. Snapshot metadata can be compared across runs to evaluate model or harness changes; event payloads are recorded evidence and must not be treated as instructions.

All three tools are read-only and require task_logs:read, with the API's agent/project visibility rules. Recording is controlled by trace_enabled on the observed agent; create_agent and update_agent accept this flag. Existing traces remain readable when recording is disabled. These tools provide evidence for user-defined reviewer agents; they do not perform automatic evaluation.

{"name":"list_agent_traces","arguments":{"agent_id":12}}
{"name":"list_task_traces","arguments":{"project_id":3,"task_id":7}}
{"name":"get_agent_trace","arguments":{"agent_id":12,"trace_id":42,"event_limit":20}}
{"name":"get_agent_trace","arguments":{"agent_id":12,"trace_id":42,"after_sequence":20}}

Tasks

First inspect get_project for column/priority short names and task type/repository IDs, and list_company_users for reporter and assignee IDs. Both reporter_id and assignee_id are required by create_task. The audit author is the token creator; the reporter is a separate explicit field.

{"name":"create_task","arguments":{"project_id":3,"title":"Implement chat search","reporter_id":4,"assignee_id":4}}
{"name":"move_task","arguments":{"project_id":3,"task_id":7,"status":"wip"}}

update_task preserves omitted fields. Its task_agents array replaces all agent/workflow assignments; files appends uploaded attachments. move_task accepts the destination column short name as status (the same API contract as the board UI), changes only the board column and uses normal API transition/approval rules. If the result contains approval_required: true, the task has not moved: report the pending approval instead of success. No execution/claim tools are exposed.

list_tasks supports q, page, per_page (1–100), filter (active or closed), sort_by, and sort_order; the API response, including pagination metadata, is preserved under result. get_project_board returns visible columns; use get_project for hidden column configuration too.

Chats and attachments

Chat access and message authorship use the token creator. The token's company and live role permissions still constrain access. A token does not gain access to chats its creator cannot see.

create_chat creates a group and automatically includes the token creator; it accepts user_ids, agent_ids, and team_ids (expanded into team agents). create_direct_chat creates/reuses a private chat with a user or agent.

update_chat_participants requires chats:update. Each supplied user_ids or agent_ids array replaces that participant type; an omitted array preserves it. [] removes all participants of that type. Read the current participant list before replacement. Agent assignments are synchronized in existing threads, preserving workflows for retained agents. Private chats and the default company chat retain their fixed membership. Removing the token creator removes subsequent MCP access to that chat.

Upload a local file on the MCP host, or send base64 content with a filename:

{"name":"upload_file","arguments":{"file_path":"/path/to/report.pdf","content_type":"application/pdf"}}
{"name":"upload_file","arguments":{"filename":"notes.txt","content_type":"text/plain","content_base64":"SGVsbG8="}}

The returned file.signed_id goes into the files array; do not send a local path as an attachment ID. Each file is limited to 20 MiB. Uploading requires file_uploads:create; sending requires chat_messages:create or chat_threads:create independently.

{"name":"create_chat_thread","arguments":{"chat_id":5,"message":{"body":"Release plan","files":["SIGNED_ID"]}}}
{"name":"send_chat_message","arguments":{"thread_id":9,"message":{"body":"See the report","files":["SIGNED_ID"],"mentioned_project_ids":[3]}}}
{"name":"list_chat_messages","arguments":{"thread_id":9}}

The message object needs a nonblank body or at least one file. File-only threads and messages are supported. Sending can trigger participating agents; a message can reopen a closed thread.

list_chats and list_chat_threads return items plus pagination (page, per_page, total_pages, total_count). Page 1 contains the newest entries. Hidden chats require include_hidden: true. get_chat_thread and list_chat_messages include file metadata, signed IDs, and download URLs; relative URLs resolve against ARMANAGE_BASE_URL.

list_chat_messages returns all messages chronologically, including the opening message. It also marks that thread's notifications read for the token creator, so it is annotated as a mutation.

Notifications

list_notifications returns up to 50 notifications for the token creator in this company, unread first, then newest within each group. It includes read status and chat/thread references and does not mark notifications read. get_unread_notification_count returns the full unread count. Both require notifications:read.

Mutation tools that accept assignment arrays treat them as complete replacements. The tool descriptions instruct the calling agent to list/get the current resource first and omit arrays that should remain unchanged.

Creating a local agent can return a one-time setup_token. That token is for registering the new Armanage client agent; it is different from the company token used by this MCP server.

Development

npm install
npm test
npm run build

The compiled stdio entrypoint is dist/index.js.