MCP Server API

agentwatch implements a Model Context Protocol (MCP) server for integration with MCP clients like Claude Desktop, OpenClaw, and others.

Transport

The MCP server supports stdio transport by default. Configure in your MCP client:

{
  "mcpServers": {
    "agentwatch": {
      "command": "agentwatch",
      "args": ["--mcp"]
    }
  }
}

Tools

session_start

Create a new monitored coding session. Optionally spawn an agent with MCP tools.

Parameters:

Name	Type	Required	Description
task	string	Yes	Description of the coding task
workdir	string	No	Working directory (optional)
session_id	string	No	Client session ID for tracking (optional)
agent	string	No	Agent to spawn (e.g., 'claude_code')

session_respond

Send keystrokes to respond to prompts. Use for menu options, confirmations, or special keys.

Parameters:

Name	Type	Required	Description
keys	string	Yes	Keystrokes to send
session_id	string	No	Target session ID (optional)

session_capture

Capture current terminal content. Useful for checking progress or diagnosing issues.

Parameters:

Name	Type	Required	Description
lines	integer	No	Number of lines to capture (default: 50)
session_id	string	No	Target session ID (optional)

session_exit

Send /exit command to Claude Code. Use before terminating the session.

Parameters:

Name	Type	Required	Description
session_id	string	No	Target session ID (optional)

session_terminate

Terminate the coding session. Refuses if program is still running.

Parameters:

Name	Type	Required	Description
session_id	string	No	Target session ID (optional)
force	boolean	No	Force terminate even if program is running

session_status

Get current status including program, state, and task context.

Parameters:

Name	Type	Required	Description
session_id	string	No	Target session ID (optional)

list_sessions

List all active coding sessions with their status.

Parameters: None

task_run

Execute a coding task in the background. Returns immediately with task ID.

Parameters:

Name	Type	Required	Description
task	string	Yes	Description of the coding task
workdir	string	Yes	Working directory
timeout	integer	No	Timeout in milliseconds (default: 300000)

task_status

Check status of a background coding task.

Parameters:

Name	Type	Required	Description
task_id	string	Yes	ID of the task to check

session_parse

Parse Claude Code session to get structured JSON. Returns state-specific summary by default.

Parameters:

Name	Type	Required	Description
session_id	string	No	Target session ID (optional)
verbose	boolean	No	Return full conversation history
force_refresh	boolean	No	Force fresh parse ignoring cache

Resources

The MCP server exposes resources for reading session state:

URI Template	Description
agentwatch://sessions	List of all tracked sessions
agentwatch://session/{name}	State of a specific session
agentwatch://session/{name}/terminal	Terminal content (ANSI stripped)
agentwatch://session/{name}/terminal/raw	Raw terminal content with ANSI codes

Proxy Tools

When a session is started with an agent (e.g., agent: "claude_code"), the agent's tools become available through prefixed names:

• claude_code:Read - Read files
• claude_code:Write - Write files
• claude_code:Edit - Edit files
• claude_code:Bash - Run shell commands
• claude_code:Grep - Search file contents
• claude_code:Glob - Find files by pattern

Proxy tools require a session_id parameter to route to the correct agent instance.