AdaptOrch MCP

AdaptOrch MCP is the public MCP wrapper for AdaptOrch: a reliability kernel that lets Claude Code route tasks, launch orchestrated runs, and pull evidence artifacts back into the chat.

Use it when a coding 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.ai.kr/app/signup

2. Create an API key → Dashboard → API Key Management → generate a key (starts with ado_)

Use that key as ADAPTORCH_CONTROL_PLANE_TOKEN:

export ADAPTORCH_CONTROL_PLANE_TOKEN="ado_..."

Free tier (Starter $0) includes API key access. See adaptorch.ai.kr for Pro/Team plans.

Related MCP server: Xylent MCP Server

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

pip

pip install adaptorch-mcp

If AdaptOrch core is not yet on PyPI, install it from GitHub first:

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

uvx (one-shot, no install)

uvx adaptorch-mcp --help

With the adaptorch dependency from GitHub:

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

Why Claude Code users feel it quickly

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

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.ai.kr

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.ai.kr \
  --http-host 127.0.0.1 \
  --http-port 8765

Health check:

python - <<'PY'
import httpx
print(httpx.get('http://127.0.0.1:8765/mcp/health').json())
PY

Claude Code MCP config

{
  "mcpServers": {
    "adaptorch": {
      "command": "adaptorch-mcp",
      "args": [
        "--transport",
        "stdio",
        "--base-url",
        "https://adaptorch.ai.kr"
      ],
      "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

Diagnostics

Print redacted local diagnostics:

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

Run a stdio smoke test. The token is passed through the child environment, not process arguments.

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

Expected output includes adaptorch_plan_catalog and the core AdaptOrch MCP tool surface.

Tool surface

Read-only tools are safe candidates for MCP auto-approve. Keep adaptorch_run and adaptorch_cancel_run manually approved.

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

Before publishing:

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
uv publish --dry-run dist/*

Then follow docs/publishing.md for PyPI Trusted Publishing or token-based uv publish.

Security

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

License

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