MCP Tools Reference#

Marcus implements MCP (Model Context Protocol) server tools that AI agents and human operators use to coordinate and execute tasks.

Tools are role-restricted: agent tools are available to coding agents; human tools are available to human operators and Cato. Both sets are available to authenticated clients with the human role.

Agent Tools#

These tools are available to all registered AI agents.

Agent Management#

async src.marcus_mcp.tools.agent.register_agent(agent_id, name, role, skills, state, project_id='')[source]#

Register a new agent with the Marcus system.

Parameters:

  • agent_id (str) – Unique identifier for the agent

  • name (str) – Display name for the agent

  • role (str) – Agent’s role (e.g., ‘Backend Developer’)

  • skills (List[str]) – List of agent’s technical skills

  • state (Any) – Marcus server state instance

  • project_id (str) – ID of the project this agent is working on. Used to scope request_next_task results so agents from concurrent experiments cannot steal tasks across project boundaries (GH-388).

Returns:

Dict with success status, registration details, and project_id.

Return type:

Dict[str, Any]

async src.marcus_mcp.tools.agent.get_agent_status(agent_id, state)[source]#

Get status and current assignment for an agent.

Parameters:

  • agent_id (str) – The agent’s unique identifier

  • state (Any) – Marcus server state instance

Returns:

Dict with agent status, current tasks, and assignment details

Return type:

Dict[str, Any]

Task Management#

Context & Collaboration#

async src.marcus_mcp.tools.context.log_decision(agent_id, task_id, decision, state)[source]#

Log an architectural decision made during task implementation.

Agents use this to document important technical choices that might affect other tasks. Decisions are automatically cross-referenced to dependent tasks.

Parameters:

  • agent_id (str) – The agent making the decision

  • task_id (str) – Current task ID

  • decision (str) – Natural language description of the decision

  • state (Any) – Marcus server state instance

Returns:

Dict with success status and decision details

Return type:

Dict[str, Any]

Project Creation#

Scheduling & Planning#

System Health#

Project Monitoring#

Human Operator Tools#

These tools are available to human operators (Cato, CLI) but not to coding agents.

Agent Administration#

async src.marcus_mcp.tools.agent.list_registered_agents(state)[source]#

List all registered agents and their current status.

Parameters:

state (Any) – Marcus server state instance

Returns:

Dict with list of all agents and their details

Return type:

Dict[str, Any]

Board Health#

Project Management#

Natural Language Features#

Prediction Tools#

AI-powered predictions for project and task outcomes. Available to human operators.

Analytics Tools#

Metrics and analytics for agents, tasks, and projects. Available to human operators.

Code Metrics Tools#

Code production and quality metrics (GitHub provider). Available to human operators.

Auth & Audit Tools#

Authentication and usage auditing. Available to admin clients.