AdaptOrch 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.

The control plane speaks MCP directly over HTTPS. Your agent connects to a URL with a bearer token. There is no package to install, no Python, no local process to keep running.

1 · Create a key

Sign in and generate a key at adaptorch.com/app/api-keys. Keys begin with ado_. Keep it in your shell, not in a config file.

export ADAPTORCH_API_KEY="ado_..."

2 · Prove the endpoint answers you

Run this before editing any config. If it lists tools, every client below will work; if it does not, no amount of client configuration will help.

curl -sS https://adaptorch.com/mcp \
  -H "Authorization: Bearer $ADAPTORCH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A valid key returns a result.tools array including adaptorch_run. Without a key the same call returns {"code":-32001,"message":"Missing bearer token"} with HTTP 401 — that response is itself proof the endpoint is reachable.

Same endpoint, same key, six dialects. These formats are not interchangeable — three of them disagree with the shape most documentation copies from Claude, and a wrong key name fails silently as a client that simply never connects.

Claude Code — one command

claude mcp add --transport http adaptorch https://adaptorch.com/mcp \
  --header "Authorization: Bearer ${ADAPTORCH_API_KEY}" \
  --header "X-Provider: ${ADAPTORCH_PROVIDER}" \
  --header "X-Provider-Model: ${ADAPTORCH_PROVIDER_MODEL}" \
  --header "X-Provider-Key: ${ADAPTORCH_PROVIDER_KEY}"

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "adaptorch": {
      "url": "https://adaptorch.com/mcp",
      "headers": { "Authorization": "Bearer ${ADAPTORCH_API_KEY}" }
    }
  }
}

Codex CLI — ~/.codex/config.toml (TOML, not JSON)

experimental_use_rmcp_client = true

[mcp_servers.adaptorch]
url = "https://adaptorch.com/mcp"
bearer_token_env_var = "ADAPTORCH_API_KEY"

Gemini CLI — ~/.gemini/settings.json (key is httpUrl)

{
  "mcpServers": {
    "adaptorch": {
      "httpUrl": "https://adaptorch.com/mcp",
      "headers": { "Authorization": "Bearer ${ADAPTORCH_API_KEY}" }
    }
  }
}

VS Code — .vscode/mcp.json (top-level servers)

{
  "servers": {
    "adaptorch": {
      "type": "http",
      "url": "https://adaptorch.com/mcp",
      "headers": { "Authorization": "Bearer ${env:ADAPTORCH_API_KEY}" }
    }
  }
}

Windsurf — ~/.codeium/windsurf/mcp_config.json (key is serverUrl)

{
  "mcpServers": {
    "adaptorch": {
      "serverUrl": "https://adaptorch.com/mcp",
      "headers": { "Authorization": "Bearer ${ADAPTORCH_API_KEY}" }
    }
  }
}

Prefer your own process, or need the bridge inside your network? Install it from PyPI. Requires Python 3.11+. The package is proprietary: downloading it grants no right to use it beyond an active plan or a signed agreement — see the terms and the licence shipped in the distribution.

pip install adaptorch-mcp

export ADAPTORCH_CONTROL_PLANE_TOKEN="$ADAPTORCH_API_KEY"
adaptorch-mcp --transport stdio --base-url https://adaptorch.com

Point any stdio-capable client at that command. It still talks to the hosted control plane, so your key and plan apply exactly as they do in § 02 — which needs no install at all and stays the shortest path.

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 MCP server (GitHub)
• Trust Center
• ingeng2004@gmail.com
• Open app