AdaptOrch MCP

AdaptOrch MCP is the MCP adapter for AdaptOrch. From Claude Code or another MCP client it submits work to the hosted control plane and returns available run status, bounded observations and artifact references. The engine owns routing and execution. Trace access requires the explicit full profile; this adapter does not expose the research-only inference-tape replay API.

Use it when your coding agent says a patch works and you want the receipt before you merge, or when a task is too large, too ambiguous, or too expensive to trust to one single-pass response.

Claude Code → AdaptOrch MCP → route topology → run with synthesis → retrieve artifacts

Get your API key

AdaptOrch requires authentication. Get your token in two steps:

1. Sign up → adaptorch.com/app/signup

2. Create an API key → adaptorch.com/app/api-keys → generate a key (starts with ado_)

Use that key as ADAPTORCH_CONTROL_PLANE_TOKEN:

export ADAPTORCH_CONTROL_PLANE_TOKEN="ado_..."
export ADAPTORCH_API_KEY="$ADAPTORCH_CONTROL_PLANE_TOKEN"

Model-backed hosted runs require BYOK. Keep provider credentials in your local environment:

export ADAPTORCH_MCP_PROVIDER="openai"
export ADAPTORCH_MCP_PROVIDER_MODEL="gpt-4.1-mini"
export ADAPTORCH_MCP_PROVIDER_API_KEY="<provider-api-key>"

These values are not MCP tool arguments or JSON body fields. The local wrapper attaches them only to run submission headers and redacts the provider key from errors. Direct HTTP clients may attach configured headers to other requests as well; check your client's secret-handling settings.

OAuth BYOK (current source): openai_codex accepts a caller-owned OAuth access token in the same key slot, with ADAPTORCH_MCP_PROVIDER_AUTH_TYPE=oauth and ADAPTORCH_MCP_PROVIDER_ACCOUNT_ID=<your-account-id>. A long-lived local MCP can use ADAPTORCH_MCP_PROVIDER_API_KEY_COMMAND=<trusted-token-helper> instead of a static key. The helper is caller-provided and must print only the fresh access token; login/refresh stays on the client. Never send refresh tokens, cookies or an entire auth file. Both the control plane and local engine must support this source contract. RQ dispatch still refuses request-scoped credentials.

Signup → MCP → dashboard run list

1. Sign up at /app/signup and open /app/api-keys.

2. Generate an ado_* key and copy the raw value once.

3. Set it only in your local MCP environment as ADAPTORCH_CONTROL_PLANE_TOKEN.

4. Run adaptorch_run or adaptorch_list_runs from Claude Code.

5. Refresh /app/runs in the dashboard to see the same tenant's run list.

한국어 요약: 가입 → /app/api-keys에서 ado_* 생성 → MCP env에 설정 → Claude Code에서 실행/목록 확인 → 대시보드 /app/runs에서 같은 실행 목록 확인.

Plan prices and monthly run quotas come from the hosted plan catalog, not the installed package. BYOK provider charges are separate from the AdaptOrch subscription; an AdaptOrch key is not a provider key.

Engine-delegated optional algorithm controls (latest)

AdaptOrch MCP forwards optional algorithm controls to the installed adaptorch engine. The wrapper does not implement these algorithms. Treat these as benchmark/eval or operator controls, not quickstart defaults.

Related MCP server: aacworkflow-mcp

Research paper

AdaptOrch MCP follows the AdaptOrch research line. Read the paper on arXiv:

• Abstract page: arxiv.org/abs/2602.16873

• HTML paper: arxiv.org/html/2602.16873v1

Install

There are three ways in. Pick by what you are: an agent, a program, or a terminal.

Release status (2026-09-20): adaptorch-mcp 0.5.2 is published with the adaptorch-mcp-client launcher and adaptorch[api]>=0.1.2,<0.2 dependency. The client-only adaptorch 0.2.0 replacement is not published. New SDK polling and response-safety features below describe this source revision; pushing it does not republish any PyPI version or revoke an earlier license grant.

Source update (2026-09-08, not a publication): this checkout adds request-scoped SDK BYOK, bounded read-only polling, subject-bound responses and typed algorithm observations. The local MCP facade uses a one-attempt, redirect-free transport and preserves requested/selected modes without exposing private diagnostics. See the client contract and verification record.

1. Hosted MCP — nothing to install (recommended)

The control plane serves MCP over HTTP at https://adaptorch.com/mcp. Any client that speaks HTTP MCP connects directly with your ado_* key:

: "${ADAPTORCH_API_KEY:?Set your AdaptOrch API key}"
: "${ADAPTORCH_MCP_PROVIDER:?Set your provider}"
: "${ADAPTORCH_MCP_PROVIDER_MODEL:?Set your model}"
: "${ADAPTORCH_MCP_PROVIDER_API_KEY:?Set your provider key}"
claude mcp add --transport http adaptorch https://adaptorch.com/mcp \
  --header "Authorization: Bearer ${ADAPTORCH_API_KEY}" \
  --header "X-Provider: ${ADAPTORCH_MCP_PROVIDER}" \
  --header "X-Provider-Model: ${ADAPTORCH_MCP_PROVIDER_MODEL}" \
  --header "X-Provider-Key: ${ADAPTORCH_MCP_PROVIDER_API_KEY}"

Set all four environment variables above before configuring model-backed runs. The CLI uses ADAPTORCH_API_KEY, ADAPTORCH_PROVIDER, ADAPTORCH_PROVIDER_MODEL, and ADAPTORCH_PROVIDER_API_KEY for these roles. Shell expansion can persist header values in client configuration; keep that file private and never commit it.

Tool discovery confirms connectivity, not model execution or a test pass. The hosted service provides supported run records and available artifacts; repository command checks require a separately configured execution environment. Shared hosted command verification is disabled by default.

Cursor, Codex, Gemini CLI, VS Code and Windsurf snippets: https://adaptorch.com/mcp-docs.

Clients that only speak stdio (Claude Desktop, older Cursor builds) reach the same endpoint through mcp-remote; no AdaptOrch install is involved:

{
  "mcpServers": {
    "adaptorch": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://adaptorch.com/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer ado_..." }
    }
  }
}

(Authorization:${...} without spaces and the value in env is the documented workaround for clients that mangle spaces in args.)

2. Python SDK — hosted API, standard library only

pip install adaptorch-client

adaptorch-client has no runtime dependencies and supports capabilities, identity, run submission/list/detail/cancellation, evidence, and artifact listings. The current source adds per-submission ProviderCredential for hosted BYOK. A repository push is separate from a PyPI release; see the source install and BYOK example.

3. This package — local engine required

adaptorch-mcp wraps the AdaptOrch parent engine in-process; it is for environments where the compatible engine is installed. Its package dependency installs the published 0.1.x engine; the hosted endpoint above needs no local engine.

uvx --python 3.12 --from adaptorch-mcp==0.5.2 adaptorch-mcp-client --help

Why Claude Code users feel it quickly

Measured: a directional paired result, with failed gates

Both arms see the same 30 units, same seeds, same session (gemma-4-31b on Cerebras), so the paired delta cancels run-to-run drift:

Paired delta +13.3pp, 95% CI [+3.3, +26.7] on this ledger family. The aggregate verdict and predefined family gate did not pass. The public evidence JSON records significant=false, aggregate_significant=false, gate_passed=false, and official_claim_allowed=false. Treat this as directional, not proven.

Scope: internal reproducible regression evidence on a synthetic ledger suite (evidence experiment paired_confirmatory_ledger, full run IDs and reproduce commands shipped with the core repository). Not an official third-party benchmark.

Run your own workload through the hosted kernel at adaptorch.com — free starter includes an API key and 5,000 platform calls/month. BYOK provider usage is billed separately; confirm current limits in the plan catalog.

Scenario benchmark projection

Architecture

Packages

The wrapper intentionally delegates runtime behavior to adaptorch.mcp_server. That keeps MCP tools, resources, prompts, safety checks, and transports aligned with the latest AdaptOrch core release.

Quickstart

Local development

git clone git@github.com:dmae97/Adaptorch-MCP.git
git clone git@github.com:dmae97/adaptorch.git  # alongside Adaptorch-MCP
cd Adaptorch-MCP
uv sync --all-packages --extra dev
uv run adaptorch-mcp --help

uv.lock pins the engine to the published adaptorch git revision. To validate the wrapper against a local engine checkout (algorithm-parity and MCP BYOK runs), install it over the pin:

make engine-local ENGINE_PATH=../adaptorch
make check

packages/adaptorch-mcp/tests/test_engine_algorithm_parity.py fails closed when the exposed synthesis modes, deprecated aliases, topologies, or output extractors drift from the engine.

stdio MCP

Use stdio for local clients such as Claude Code or desktop MCP hosts.

export ADAPTORCH_CONTROL_PLANE_TOKEN="<your-token>"
adaptorch-mcp --transport stdio --base-url https://adaptorch.com

HTTP MCP

Use HTTP for local gateways, reverse proxies, or remote MCP clients.

export ADAPTORCH_CONTROL_PLANE_TOKEN="<upstream-adaptorch-token>"
export ADAPTORCH_MCP_HTTP_AUTH_TOKEN="<client-facing-mcp-token>"

adaptorch-mcp \
  --transport http \
  --base-url https://adaptorch.com \
  --http-host 127.0.0.1 \
  --http-port 8765

Authenticated health check:

python - <<'PY'
import os
from urllib.request import Request, urlopen

request = Request(
    "http://127.0.0.1:8765/mcp/health",
    headers={"Authorization": f"Bearer {os.environ['ADAPTORCH_MCP_HTTP_AUTH_TOKEN']}"},
)
with urlopen(request) as response:
    print(response.read().decode("utf-8"))
PY

CLI and environment reference

For adaptorch-mcp, the public wrapper resolves the control-plane URL in this order: explicit --base-url, then trimmed/validated ADAPTORCH_CONTROL_PLANE_BASE_URL, then the hosted fallback https://adaptorch.com. adaptorch-mcp-smoke keeps a local-dev fallback of http://127.0.0.1:8000 when no base URL is configured. Pass --base-url explicitly in checked-in MCP client configs for reproducible behavior.

Claude Code MCP config

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

More templates:

• examples/claude_desktop_config.json

• examples/omk.mcp.json

• examples/mcp-http.env.example

Checked-in examples use placeholders or environment interpolation. Fill real URLs and tokens only in local, uncommitted config files.

Diagnostics

Print redacted local diagnostics:

adaptorch-mcp-doctor
adaptorch-mcp-doctor --json
adaptorch-mcp-doctor --strict

Run a stdio smoke test. The token is passed through the child environment, not process arguments. If no base URL is supplied, smoke targets http://127.0.0.1:8000 for local development.

export ADAPTORCH_CONTROL_PLANE_TOKEN="<your-token>"
adaptorch-mcp-smoke --base-url https://adaptorch.com

Expected JSON includes "ok": true, adaptorch_plan_catalog, and the expected core tool subset. Doctor JSON also includes redacted controlPlane metadata for the resolved base-url source. Add repeatable --expected-tool <name> flags when validating a specific hosted/core release.

Tool surface

The default remote profile exposes the nine tools other than adaptorch_get_traces and adaptorch_route_topology. adaptorch_get_run publishes a closed outputSchema and safe structuredContent; its optional correctness_wall is advisory observability, not a correctness proof, selector decision, or apply authorization.

For trusted local clients, auto-approve only tools whose outputs are safe for that client. Keep adaptorch_run and adaptorch_cancel_run manually approved. For shared or production clients, avoid auto-approving run, artifact, and trace readers unless those payloads are already sanitized.

Branding assets

• GitHub hero: assets/readme-hero.png

• GitHub flow diagram: assets/mcp-flow.png

• GPT-image-2.0 raster prompt brief: docs/brand/gpt-image-2-brief.md

Public release checklist

The current local MCP wrapper is blocked by the public-wheel gate because it depends on the private engine. Build/test success and a publish dry-run are not permission to publish that wheel. The engine-free SDK/CLI have separate wheel gates.

For local validation only:

uv run ruff check packages/adaptorch-mcp
uv run mypy packages/adaptorch-mcp/src
uv run pytest packages/adaptorch-mcp/tests -q
uv run python -m build packages/adaptorch-mcp --outdir dist

Publishing requires an independently passing public-wheel gate and explicit release approval. Only then follow docs/publishing.md for the applicable public package.

Security

Never commit .env, API keys, bearer tokens, private keys, or MCP client tokens. See SECURITY.md.

License

Proprietary — Copyright ClassicMate. All rights reserved. See LICENSE.