agent-mcp-adapter

Non-invasive MCP adapter for XAgent HTTP APIs.

The adapter runs as a separate MCP stdio server and calls XAgent through its public HTTP API. It does not import XAgent internals, read the database, or bypass auth/owner scope.

Configuration

$env:XAGENT_BASE_URL = "http://127.0.0.1:3000"

# Optional. Forward auth exactly like a normal HTTP client.
$env:XAGENT_AUTHORIZATION = "Bearer <token>"

# Optional JSON object for extra headers.
$env:XAGENT_HEADERS_JSON = '{"x-tenant-id":"tenant-1"}'

# Optional request timeout.
$env:XAGENT_TIMEOUT_MS = "30000"

# Safety default: only read-only tools are exposed unless this is set to false.
$env:XAGENT_MCP_READONLY = "true"

# Optional comma-separated allowlist. Applied together with read-only filtering.
$env:XAGENT_MCP_ALLOWED_TOOLS = "xagent_health,xagent_list_sessions"

# Optional comma-separated response header allowlist. Headers are hidden by default.
$env:XAGENT_RESPONSE_HEADER_ALLOWLIST = "x-request-id"

Run

From npm:

npx agent-mcp-adapter

For local development:

npm install
npm run build
npm start

Drift Check

Set XAGENT_ROUTES_FILE to the target agent route source file, then verify that the adapter still covers the current public routes:

$env:XAGENT_ROUTES_FILE = "C:\path\to\agent-repo\packages\agent-channel-web\src\routes\requests.ts"
npm run check:xagent-routes

Design

• Every tool maps to a public XAgent route.
• Tool input is converted into HTTP path/query/body.
• Tool input is validated by the adapter before any upstream HTTP call.
• Tool output includes structuredContent with status, ok, body, and request metadata.
• Response headers are hidden unless explicitly allowlisted.
• The default exposure mode is read-only; mutation tools require XAGENT_MCP_READONLY=false.
• SSE/WebSocket streaming is represented by a polling tool, xagent_wait_for_session_idle.
• Multipart submit/edit routes are exposed through explicit base64 file upload tools.

Included API Tools

• xagent_health
• xagent_health_deep
• xagent_runtime_bootstrap
• xagent_list_sessions
• xagent_create_session
• xagent_update_session_title
• xagent_list_skills
• xagent_generate_suggested_questions
• xagent_get_conversation_preview
• xagent_get_conversation
• xagent_submit_request
• xagent_submit_request_multipart
• xagent_submit_session_request
• xagent_submit_session_request_multipart
• xagent_cancel_session
• xagent_retry_session
• xagent_edit_latest_request
• xagent_edit_latest_request_multipart
• xagent_answer_pending_input
• xagent_upsert_run_annotation
• xagent_list_favorites
• xagent_list_session_annotations
• xagent_create_share
• xagent_get_shared_conversation
• xagent_wait_for_session_idle

Multipart Input

Multipart tools accept base64 file content:

{
  "body": {
    "inputText": "Inspect this alarm file.",
    "idempotencyKey": "idem-1",
    "files": [
      {
        "fileName": "alarm.txt",
        "declaredMimeType": "text/plain",
        "base64": "YWxhcm0="
      }
    ]
  }
}

Exposing Write Tools

To expose all built-in tools:

$env:XAGENT_MCP_READONLY = "false"

To expose only a narrow set:

$env:XAGENT_MCP_READONLY = "false"
$env:XAGENT_MCP_ALLOWED_TOOLS = "xagent_submit_request,xagent_get_conversation,xagent_wait_for_session_idle"