MCP Server

The Model Context Protocol (MCP) server allows compatible AI clients (editors, agent tools) to query and control AzurPilot programmatically. It operates as an alternative integration channel rather than replacing the WebSocket API.

Mounting Modes

Mode	Endpoint	Description
Embedded in WebUI	http://<host>:25548/mcp/sse	Default; reuses WebUI process
Standalone Service	python mcp_server_sse.py (port 22268)	Debugging and isolated setups

Port 22268 Collision

Standalone MCP services and standalone OCR services default to port 22268. If hosting both concurrently on the same machine, modify one of the ports.

Authentication

The MCP service authenticates using the WebUI password (--key or deploy.yaml):

Header	Format
Standard (Recommended)	Authorization: Bearer <password>
Compatibility Header	X-API-Key: <password>
Query Parameter	?key=<password> (only for clients that cannot set headers)

Unauthenticated requests receive HTTP 401. Modifying passwords requires restarting the server.

Query Parameters Expose Credentials

Query parameters appear in server logs, history, and screenshots. Use HTTP headers whenever supported.

Client Configuration

Local connection:

{
  "mcpServers": {
    "azurpilot": {
      "url": "http://127.0.0.1:25548/mcp/sse",
      "headers": { "Authorization": "Bearer <WebUI-Password>" }
    }
  }
}

Remote or local network:

{
  "mcpServers": {
    "azurpilot": {
      "url": "http://<IP_ADDRESS>:25548/mcp/sse",
      "headers": { "Authorization": "Bearer <WebUI-Password>" }
    }
  }
}

Available Tools

18 tools are currently registered:

Category	Tool	Function
Instance	list_instances	Lists all instances
Instance	get_status	Returns instance status
Instance	start_instance	Starts an instance worker
Instance	stop_instance	Stops an instance worker
Tasks	list_tasks	Lists all available tasks
Tasks	get_task_help	Retrieves task documentation
Tasks	trigger_task	Triggers immediate task execution
Tasks	get_scheduler_queue	Inspects scheduler queue
Tasks	clear_scheduler_queue	Purges scheduler queue
Telemetry	get_current_running_task	Returns active task
Telemetry	get_resources	Returns resource gauges
Telemetry	get_config	Reads instance settings
Telemetry	get_recent_logs	Retrieves recent logs
Telemetry	get_screenshot	Returns current frame capture
Config	update_config	Writes configuration values
Maintenance	restart_emulator	Reboots emulator
Maintenance	restart_adb	Restarts ADB daemon
Maintenance	update_alas	Updates AzurPilot core code

Schemas Provided Dynamically

MCP clients fetch JSON Schemas dynamically via tools/list.

Common Use Cases

Health Checks

1. list_instances           → Check active instances
2. get_status(instance)     → Inspect worker state and active task
3. get_recent_logs(...)     → Check for error traces
4. get_resources(...)       → Evaluate oil and coin levels

Interventions

trigger_task(instance, task)   → Run task on demand
clear_scheduler_queue(...)     → Reset backlog during troubleshooting
restart_adb(...)               → Recover dropped ADB connections

Destructive Operations

update_alas, restart_emulator, and clear_scheduler_queue disrupt running tasks. Ensure agents understand the consequences before delegating access.

Supervise Configuration Changes

update_config writes directly to disk, altering subsequent schedules. External edits lack optimistic revision locks and may overwrite concurrent user adjustments.

Comparison with WebSocket API

Feature	MCP Server	WebSocket API
List / Start / Stop Instances	✅	✅
Detailed Configuration Edits	Basic (update_config)	✅ Comprehensive
Real-time Event Streaming	❌	✅
Scheduler Canvas Orchestration	❌	✅
Agent Integration Out-of-the-Box	✅	Requires custom client