AdaptOrch MCP Server

AdaptOrch exposes its control-plane through the Model Context Protocol (MCP) so coding agents can submit runs, poll status, fetch artifacts and traces, and request topology routing.

The server is a direct JSON-RPC implementation (not FastMCP). Tools are published as static schemas, resources and prompts are listed alongside them, and every tool result is returned as a JSON string in content[0].text.

Protocol version 2025-11-25 is the default; 2024-11-05, 2025-03-26, and 2025-06-18 are also supported.

AdaptOrch MCP is a Python package (requires Python 3.11+). Install the client extra, then run the adaptorch-mcp console script.

# stdio MCP server (console script)
pip install 'adaptorch[mcp]'
adaptorch-mcp --transport stdio --base-url https://control-plane.example.com

# HTTP+SSE transport requires the api extra
pip install 'adaptorch[api]'
adaptorch-mcp --transport http --http-host 127.0.0.1 --http-port 8765

For Claude Desktop / Claude Code, add an entry to mcp.json. stdio is the default and recommended transport; HTTP+SSE is available for remote control planes.

stdio (default, recommended)

{
  "mcpServers": {
    "adaptorch": {
      "command": "adaptorch-mcp",
      "args": ["--transport", "stdio", "--base-url", "https://control-plane.example.com"],
      "env": { "ADAPTORCH_CONTROL_PLANE_TOKEN": "${ADAPTORCH_CONTROL_PLANE_TOKEN}" }
    }
  }
}

stdio via uvx (after a PyPI release)

{
  "mcpServers": {
    "adaptorch": {
      "command": "uvx",
      "args": ["--from", "adaptorch[mcp]", "adaptorch-mcp", "--base-url", "https://control-plane.example.com"],
      "env": { "ADAPTORCH_CONTROL_PLANE_TOKEN": "${ADAPTORCH_CONTROL_PLANE_TOKEN}" }
    }
  }
}

HTTP+SSE (Bearer)

{
  "mcpServers": {
    "adaptorch-http": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": { "Authorization": "Bearer ${ADAPTORCH_MCP_HTTP_AUTH_TOKEN}" }
    }
  }
}

The server publishes 10 tools. Each result is a JSON string in content[0].text; failures set isError. Badges reflect the MCP annotations (read-only, destructive, idempotent, open-world).

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "adaptorch_run",
    "arguments": { "prompt": "${TASK_PROMPT}", "synthesis_mode": "robust",
                   "wait_for_terminal": true, "timeout_seconds": 120.0 } } }
// result text -> { "run_id": "${RUN_ID}", "status": "SUCCEEDED",
//                  "telemetry": { "ensemble": { "selected_model_id": "${MODEL}" } } }

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "adaptorch_get_run", "arguments": { "run_id": "${RUN_ID}" } } }
// result text -> { "run_id": "${RUN_ID}", "status": "RUNNING" }

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": { "name": "adaptorch_get_artifacts", "arguments": { "run_id": "${RUN_ID}" } } }
// result text -> { "run_id": "${RUN_ID}", "artifacts": { "${NAME}": "${URL}" } }

{ "jsonrpc": "2.0", "id": 4, "method": "tools/call",
  "params": { "name": "adaptorch_list_runs", "arguments": { "limit": 20, "status": "SUCCEEDED" } } }
// result text -> { "runs": [ ... ], "page": 1, "page_size": 20 }

{ "jsonrpc": "2.0", "id": 5, "method": "tools/call",
  "params": { "name": "adaptorch_get_traces", "arguments": { "run_id": "${RUN_ID}" } } }
// result text -> { "run_id": "${RUN_ID}", "traces": [ ... ] }

{ "jsonrpc": "2.0", "id": 6, "method": "tools/call",
  "params": { "name": "adaptorch_cancel_run", "arguments": { "run_id": "${RUN_ID}" } } }
// result text -> { "run_id": "${RUN_ID}", "status": "CANCELLED" }

{ "jsonrpc": "2.0", "id": 7, "method": "tools/call",
  "params": { "name": "adaptorch_route_topology",
    "arguments": { "subtasks": [ { "id": "t1" }, { "id": "t2" } ],
                   "dependencies": [ { "from": "t1", "to": "t2" } ] } } }
// result text -> { "topology": "${TOPOLOGY}", "stages": [ ["t1"], ["t2"] ],
//                  "features": { "node_count": 2, "edge_count": 1 } }

{ "jsonrpc": "2.0", "id": 8, "method": "tools/call",
  "params": { "name": "adaptorch_server_metrics", "arguments": {} } }
// result text -> { "tool_calls": 0, "tool_errors": 0, "p50_latency_ms": 0.0, "p95_latency_ms": 0.0 }

{ "jsonrpc": "2.0", "id": 9, "method": "tools/call",
  "params": { "name": "adaptorch_capabilities", "arguments": {} } }
// result text -> { "synthesis_modes": ["paper","robust","robust_lite","stable_hybrid","fourier_aggressive"], ... }

{ "jsonrpc": "2.0", "id": 10, "method": "tools/call",
  "params": { "name": "adaptorch_plan_catalog", "arguments": {} } }
// result text -> { "schemaVersion": "adaptorch.cloud_plan_catalog.v1", "plans": [ ... ] }

stdio relies on a local trust model plus a control-plane token. HTTP+SSE adds bearer auth, origin allow-listing, protocol-version checks, and a payload size cap. All tokens are injected through environment variables and are never hard-coded.

Three common flows cover most agent integrations.

1 · Run and collect

Call adaptorch_run with wait_for_terminal, then read the result with adaptorch_get_run, adaptorch_get_artifacts, and adaptorch_get_traces.

{ "name": "adaptorch_run",
  "arguments": { "prompt": "${TASK_PROMPT}", "wait_for_terminal": true } }
// then
{ "name": "adaptorch_get_artifacts", "arguments": { "run_id": "${RUN_ID}" } }

2 · Pre-route a DAG

adaptorch_route_topology computes a recommended topology locally — it does not call the control-plane.

{ "name": "adaptorch_route_topology",
  "arguments": { "subtasks": [ { "id": "t1" }, { "id": "t2" } ],
                 "dependencies": [ { "from": "t1", "to": "t2" } ] } }

3 · Operate

List recent runs with adaptorch_list_runs and stop an in-flight run with adaptorch_cancel_run. The adaptorch_run_prompt and adaptorch_get_run_prompt prompts wrap these calls for agents.

• Launcher not found: use the adaptorch-mcp console script or scripts/run_adaptorch_mcp.sh.
• Token missing: set ADAPTORCH_CONTROL_PLANE_TOKEN; a remote --base-url requires it.
• Framing mismatch: match --stdio-framing (newline default vs content-length).
• HTTP 401 / 403: check the bearer token and the Origin allow-list.
• HTTP 413: the request body exceeds the payload size cap.
• verification_commands rejected: disabled unless ADAPTORCH_MCP_ALLOW_VERIFICATION_COMMANDS is set.
• Smoke test: GET /mcp/health and GET /mcp/sse?once=true.

• Adaptorch-MCP (GitHub)
• AdaptOrch monorepo (GitHub)
• Trust Center
• ict03@rfems.com
• Open app