harness_to_mcp: Expose harness internal tools as a standard MCP server

Contents: Features | Install | Demo | How it works | Notes

Turn any agent harness (Claude Code, Codex, OpenClaw, OpenCode, ...) into an MCP server.

How: harness_to_mcp sits between the harness and its LLM API, grabs the tool list from the hijacked request, and routes MCP tools/call back into the harness tool loop.

▮ Features

• ☑ One command to expose claude / codex / openclaw / opencode as an MCP server
• ☑ Co-locates one MCP HTTP server and one hijack LLM API server on the same port
• ☑ Extracts the harness tool list automatically from intercepted LLM requests
• ☑ Mirrors captured harness system prompt into MCP initialize.result.instructions
• ☑ Forwards MCP tools/call into the harness tool loop and maps the tool result back
• ☑ Compatible LLM API protocols:
• OpenAI Chat Completions (openclaw, opencode)
• OpenAI Responses (codex)
• Anthropic Messages (claude)
• ☑ Isolated harness config — will not pollute the user's own config and logs
• ☑ One harness process per MCP session, the harness process is stopped automatically on session close
• ☑ Plain server mode for bringing your own harness
• ☑ Pure-Python, clean dependencies — easy to hack and vibe-code on

▮ Install

pip install harness_to_mcp

The target harness CLI (claude, codex, openclaw, ...) needs to be installed separately and available on PATH.

▮ Demo

#### 1. One-liner to expose a harness as MCP

harness_to_mcp claude
# or: harness_to_mcp codex / openclaw / opencode

Each command starts a server and launches one corresponding harness instance. The harness is started with an isolated config, so it will not touch the user's own config or logs.

The MCP endpoint is then ready at:

http://127.0.0.1:<port>/mcp

Point any MCP client (Claude Desktop, Cursor, your own script, ...) at it and the harness's internal tools show up as standard MCP tools.

You can inspect the exposed tools with python examples/list_tools.py.

#### 2. Only run the server (plug in any harness)

harness_to_mcp

This mode starts only the server. It listens on MCP plus all hijack LLM API routes, but does not launch any harness by itself. Configure your harness's LLM API as the hijack API, send one request, and its internal tools are exposed on MCP. This is also how you plug in claude / codex / openclaw / opencode with your own custom config.

Exposed endpoints:

#### 3. Python API

We also provide a Python interface:

from harness_to_mcp import HarnessToMcp

with HarnessToMcp(port=9330) as server:
    print(server.mcp_url)          # e.g. http://127.0.0.1:9330/mcp
    print(server.hijack_base_url)  # e.g. http://127.0.0.1:9330/harness_to_mcp

▮ How it works

sequenceDiagram
    participant C as MCP Client
    participant M as harness_to_mcp<br/>MCP Server
    participant H as harness_to_mcp<br/>Hijack API Server
    participant R as Harness

    C->>M: initialize
    M->>R: launch harness session
    R->>H: send hijacked LLM API request
    H-->>M: extract tool list from request
    M-->>C: tools/list

    C->>M: tools/call
    M-->>H: resolve waiting request as tool call
    H-->>R: return tool call payload
    R->>R: execute internal tool
    R->>H: send next request with tool result
    H-->>M: match tool_call_id and deliver tool result
    M-->>C: MCP tool response

In short:

1. MCP client calls initialize → we spawn a harness.
2. The harness fires off its first LLM request (with the tool schema in it) → we intercept the request, extract the tool list, and reply to the MCP client with tools/list.
3. MCP client calls tools/call → we complete the pending LLM response as a tool call, the harness executes its internal tool, and sends the result back in the next LLM request.
4. We match the tool_call_id, extract the tool result, and return it as the MCP tool response.

▮ Notes

• The LLM API layer is split into reusable adapters: chat completions, responses, messages.
• The harness launcher layer is split per-harness: opencode, openclaw, codex, claude.
• Plain server mode (harness_to_mcp with no subcommand) never auto-launches a harness.
• Intercepted waiting requests are kept alive with periodic heartbeat bytes until MCP receives the next tool call.

▮ License

The MIT License