adaptorch-mcp

adaptorch-mcp

Installable Python wrapper for the AdaptOrch MCP server.

The package runs a hardened facade over adaptorch.mcp_server, so routing and synthesis stay aligned with AdaptOrch core without copying those algorithms into the wrapper. The default remote exposure profile keeps local topology and trace oracles out of the public MCP surface.

Install

pip install --upgrade "adaptorch-mcp>=0.5.2,<0.6"
adaptorch-mcp-client --help

Use adaptorch-mcp-client to select this hardened wrapper explicitly. The legacy adaptorch-mcp name is retained, but the engine also installs that name and some installers can overwrite it. This release supports the adaptorch 0.1.x engine, not the planned code-free 0.2.x meta-package.

If AdaptOrch is not published to your package index yet:

pip install "adaptorch[api] @ git+https://github.com/dmae97/adaptorch.git"
pip install adaptorch-mcp

One-shot with uvx:

uvx --from "adaptorch-mcp==0.5.2" adaptorch-mcp-client --help
uvx --from "adaptorch-mcp==0.5.2" --with "adaptorch[api] @ git+https://github.com/dmae97/adaptorch.git" adaptorch-mcp-client --help

For contributors inside this monorepo:

uv sync --all-packages --extra dev
uv run adaptorch-mcp-client --help

Run stdio MCP

Use stdio for Claude Code, Claude Desktop, and other local MCP hosts. The upstream token is the AdaptOrch API key issued at https://adaptorch.com/app/api-keys (ado_live_*, or ado_test_* for test mode; legacy ak_* keys remain accepted).

export ADAPTORCH_CONTROL_PLANE_TOKEN="<ado_live_your-key>"
adaptorch-mcp-client --transport stdio --base-url https://adaptorch.com

For a BYOK-only control plane, configure the provider credential in the MCP process environment:

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

The key is never exposed as an MCP tool argument or JSON body field. It is sent only on run submission, redacted from errors, and omitted from status, artifact, usage, and catalog requests. Older engines without provider-credential support fail closed; source checkouts can install the current engine with make engine-local ENGINE_PATH=../adaptorch.

Runs submitted through this wrapper are stamped metadata.connector_source="mcp" by the engine, so they appear in the dashboard MCP status card and https://adaptorch.com/app/runs for the key's tenant.

Run HTTP MCP

Use HTTP for local gateways, reverse proxies, or remote MCP clients. Keep the client-facing MCP token separate from the upstream AdaptOrch token.

export ADAPTORCH_CONTROL_PLANE_TOKEN="<upstream-adaptorch-token>"
export ADAPTORCH_MCP_HTTP_AUTH_TOKEN="<client-facing-mcp-token>"  # must differ from upstream

adaptorch-mcp-client \
  --transport http \
  --base-url https://adaptorch.com \
  --http-host 127.0.0.1 \
  --http-port 8765 \
  --http-auth-token "$ADAPTORCH_MCP_HTTP_AUTH_TOKEN"

Health and metrics require the client-facing bearer token:

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

The built-in HTTP listener is loopback-only. Put an authenticated TLS reverse proxy in front of it for remote clients.

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

Environment variables

Engine-delegated optional controls

The wrapper forwards these controls to the installed adaptorch engine; it does not implement routing, synthesis, or benchmark algorithms itself. See the root configuration guide for non-env controls such as manifest_canonical_sha256, pass_rate_credit, quality_signal, prefer_multi_model_ensemble_singleton, and MCP prefer_ensemble_singleton.

Tool surface

adaptorch_get_traces and adaptorch_route_topology are available only when ADAPTORCH_MCP_EXPOSURE_PROFILE=full. In the default profile, run diagnostics and telemetry are redacted, run-resource templates are hidden, completions are disabled, and server events are not broadcast to SSE subscribers.

For modern MCP clients, adaptorch_get_run advertises a closed outputSchema and returns structuredContent reconstructed from the wrapper's own allowlist projection. Its optional correctness_wall is bounded advisory observability from the installed parent AdaptOrch engine. Even a PASS verdict is not a correctness proof, active-selector decision, or authorization to apply a candidate; inspect its claim_boundary and recommended_action.

For a control plane with the new modelstudio-maas provider, see ModelStudio Token Plan. This is a source-checkout integration, not a claim that the hosted service has been upgraded.

Security boundary

The hardened defaults reduce direct algorithm-oracle, transport, and token-confusion risk. They do not provide DRM: reverse engineering cannot be made impossible for distributed Python code or a queryable black-box service. Keep proprietary algorithms and rate-limit/model-extraction defenses on the hosted control plane; treat full as trusted local/operator mode only.

Remote control-plane URLs require HTTPS by default. Plain HTTP is accepted only for exact loopback addresses, unless the development-only ADAPTORCH_MCP_ALLOW_INSECURE_CONTROL_PLANE=1 opt-in is set. The HTTP MCP listener itself accepts only loopback binds.

Diagnostics and smoke tests

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

The doctor command reports package availability, expected MCP tools, redacted environment metadata, and controlPlane base-url plus transport-policy validity without printing token values. The control-plane token entry adds formatRecognized (prefix check against the dashboard ado_*/ak_* key contract, booleans only). --strict fails for invalid exposure profiles, malformed URLs, or remote plaintext URLs without the explicit development opt-in.

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

Expected JSON includes "ok": true, adaptorch_plan_catalog, and the expected core tool subset. If no base URL is supplied, smoke targets http://127.0.0.1:8000 for local development. Add repeatable --expected-tool <name> flags when validating a specific hosted/core release.

Example configs

• ../../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. For shared or production clients, avoid auto-approving run, artifact, and trace readers unless those payloads are already sanitized.

HTTP app factory

create_default_mcp_http_app() embeds the canonical AdaptOrch MCP HTTP ASGI app. It requires an upstream control-plane token in the environment.

export ADAPTORCH_CONTROL_PLANE_TOKEN="<upstream-adaptorch-token>"
export ADAPTORCH_CONTROL_PLANE_BASE_URL="https://adaptorch.com"
export ADAPTORCH_MCP_HTTP_AUTH_TOKEN="<client-facing-mcp-token>"  # distinct from upstream

from adaptorch_mcp import create_default_mcp_http_app

app = create_default_mcp_http_app()

License

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