AdaptOrch

AdaptOrch MCP

[AdaptOrch MCP — route, run, and retrieve evidence from Claude Code]

adaptorch.com · adaptorchctl 한국어 가이드 · Configuration · Tools · Claude Code guide · GitHub Action · GitHub Marketplace · [Remote service boundary](docs/remote-service-distribution.md) · Publishing · Paper

[Python 3.11+] [MCP] [License Proprietary] [Distribution migration pending] [Live on adaptorch.com] [arXiv 2602.16873]

AdaptOrch MCP is the remote-only 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 private engine owns routing and execution on the server; it is not installed by this package. 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 hosted adaptorch engine. The public client does not implement these algorithms. Treat these as benchmark/eval or operator controls, not quickstart defaults.

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

[Figure from the AdaptOrch arXiv HTML paper]

_{Figure preview is sourced from the arXiv HTML version.}

Install

There are four ways in. Pick by what you are: a Claude Code user, an agent, a program, or a terminal.

Release status (2026-11-03): adaptorch-mcp 0.6.1, adaptorch-cli 0.1.6 and adaptorch-client 0.1.6 are published. adaptorch-mcp 0.6.x is a remote client with no engine dependency. It forwards MCP calls to POST /v1/mcp; adaptorch.com serves that path since 2026-11-03 (before that, every 0.6.0 call failed with "Remote MCP request failed"). adaptorch-mcp 0.3.0–0.5.2 depend on the engine distribution and do not install against the code-free adaptorch 0.2.0; use 0.6.0 or later.

Source update (2026-10-26, not a publication): the workspace engine pin moves to a490658c, the revision the engine's runbook last recorded as served by the hosted control plane. adaptorch-client and adaptorch-cli 0.1.5 reuse keep-alive connections for reads (TLS 1.2 minimum, one CA-store load per client), type the evidence verification verdict, and parse large responses about twice as fast. The local MCP connector shares the same transport, its HTTP listener is bounded, and adaptorchctl run wait now honours --timeout. See network and transport notes.

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.

Claude Code plugin

The plugin adds the AdaptOrch MCP tools and a skill that tells Claude when and how to use them. It needs uv on your PATH.

claude plugin marketplace add dmae97/Adaptorch-MCPclaude plugin install adaptorch@adaptorch

Configure the AdaptOrch service key using /plugin configure adaptorch@adaptorch. For model-backed runs, also configure a provider, model ID and provider key in the dialog. Sensitive fields are stored in Claude Code's credential store. The plugin runs the published adaptorch-mcp 0.6.x remote client over stdio. Details are in plugins/adaptorch.

Kimi Code, Grok Build and Grok Bot

This repository also ships a Kimi Code plugin and a Grok Build plugin with the same public MCP client and an AdaptOrch skill. The Cursor plugin is the starting point for Grok Bot marketplace review. Setup, authentication and the separate listing status are documented in agent platform integrations. These are AdaptOrch-maintained integrations; hosting a marketplace in this repository does not imply listing in or endorsement by an upstream marketplace.

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 — remote MCP client

adaptorch-mcp 0.6.0 is a remote client over the hosted endpoint above; it depends only on adaptorch-client and never installs or imports the private engine.

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

Why Claude Code users feel it quickly

Measured: a directional paired result, with failed gates

[AdaptOrch measured paired run — baseline 86.7% vs verified 100.0% on 30 shared ledger tasks, +13.3pp, 95% CI [+3.3, +26.7]]

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 — the $0 Starter plan includes an API key and 50 admitted runs/month. BYOK provider usage is billed separately; confirm current limits in the plan catalog.

Scenario benchmark projection

[GLM-5.2 Max with AdaptOrch — confidence-weighted scenario benchmark projection]

_{Confidence-weighted scenario projection (8.0/10). Projected uplift, not measured benchmark results.}

Architecture

[AdaptOrch MCP route-run-evidence flow]

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 [email protected]:dmae97/Adaptorch-MCP.gitgit clone [email protected]:dmae97/adaptorch.git  # alongside Adaptorch-MCPcd Adaptorch-MCPuv sync --all-packages --extra devuv 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=../adaptorchmake 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

Without the token, stdio still starts so registries can inspect it: initialize, ping and tools/list come from a pinned catalog shipped in the package, and every tool call fails with -32001 before any network request. Listing tools proves only that the server starts; it does not run anything. The root Dockerfile builds this stdio server from a pinned commit; Glama uses the build spec in docs/glama.md.

stdio over SSH

To run the wrapper on another machine, let SSH carry stdio. Keep the tokens in that host's environment, not on the command line, and make sure the remote shell prints nothing of its own:

claude mcp add adaptorch -- ssh -T build-host /opt/adaptorch/bin/adaptorch-mcp \  --transport stdio --base-url https://adaptorch.com

• -T disables the pseudo-terminal, so no CR/LF translation or echo reaches the JSON-RPC stream. A login banner or an echo in a remote rc file corrupts it.
• SSH does not forward ADAPTORCH_CONTROL_PLANE_TOKEN by default. Set it on the remote host, or allow it explicitly with SendEnv/AcceptEnv.
• Check the path before configuring a client: adaptorch-mcp-smoke --command "ssh -T build-host /opt/adaptorch/bin/adaptorch-mcp". The smoke reports non-JSON stdout as such and no longer stalls when the SSH session keeps stdout open after the answers arrive.
• When the session drops, the server sees EOF on stdin and exits; a run it already submitted keeps going on the control plane. Read it again with resume_run_id or adaptorchctl run wait, never by submitting again.

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 osfrom 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

The listener binds loopback only and caps concurrent connections at ADAPTORCH_MCP_MAX_SSE_SUBSCRIBERS (engine default 64) plus 64 for ordinary requests; beyond that it answers 503 instead of queueing unbounded work. Shutdown waits at most 10 seconds for open streams, and responses carry no server header.

Network and transport notes

TLS uses the system trust store with certificate and hostname verification and refuses anything older than TLS 1.2. Ambient HTTP(S)_PROXY variables and redirects are still ignored; SSL_CERT_FILE still selects a private CA bundle. On Linux the client acknowledges response segments immediately, so a server that leaves Nagle on cannot stall a reused connection on the 40 ms delayed-ACK timer.

Measured on loopback HTTPS (100 sequential reads, this source revision): 4.1-5.6 ms per read with a new connection per request, 0.4-0.6 ms with keep-alive. Across a real network the saving per read is the TCP and TLS handshake round trips. Parsing a 3 MB, 5,000-run list page dropped from 268 ms to 129 ms. These are local micro-benchmarks, not end-to-end claims.

There is no UDP transport: MCP defines stdio and Streamable HTTP, and every AdaptOrch API is HTTP over TCP. HTTP/3 (QUIC) is not available in the standard library this client is limited to.

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 uses the same order and fallback (before 0.6.1 it fell back to http://127.0.0.1:8000). 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

Runs may include verification_diagnostics with version marker verification_diagnostics_schema_version: "verification.diagnostics/v1". These bounded observations do not change the result. project_report is an untrusted project claim; process_spawn is a verifier launch observation. Only closed codes, scope and the four PDF tool names are exposed; logs remain private. Malformed optional metadata is omitted without losing the run. See tools.

Print redacted local diagnostics:

adaptorch-mcp-doctoradaptorch-mcp-doctor --jsonadaptorch-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 https://adaptorch.com; pass --base-url http://127.0.0.1:8000 for a local control plane. The default timeout is 30 seconds.

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. The engine's read-only adaptorch_navigate_evidence (fixed evidence-pack navigation, algorithm_version defaulting to graph_v5) is likewise full-profile only. 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.

GitHub Action

Run a task from a trusted workflow with the GitHub Action. The Marketplace preview uses a separate repository containing only the remote Action and public API client; no private engine is installed on the runner. It reports execution and verification separately and can optionally save a JSON run report. API credentials belong in GitHub Secrets. Its tests use a loopback fixture and do not incur model charges; compatibility with a hosted deployment still needs a real run.

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-mcpuv run mypy packages/adaptorch-mcp/srcuv run pytest packages/adaptorch-mcp/tests -quv 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.