@modelprofile.com/crossharness-mcp

Connection-first MCP server for interacting with AI coding harness sessions through their explicit web-server APIs.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Transport Contract

Crossharness only talks to explicitly connected harness web servers:

Harness	Server transport	Support
OpenCode	http:// or https://	list, read, send, health
Codex	ws:// or wss:// app-server	list, read, send, health
Claude Code	none	rejected at connection time

There is no local session-store access, CLI invocation, process spawn, server discovery, auto-start, restart, or fallback. If a connection or request fails, the operation fails.

Claude Code 2.1.219 does not expose a URL-addressable session server. Its CLI and Agent SDK are local process/library interfaces, so it cannot participate in this server-only contract yet.

Connection Flow

Harness operations start with connect_harness:

connect_harness {
  harness: "opencode",
  serverUrl: "http://127.0.0.1:4096",
  directory: "/absolute/path/on/server"
}

The result contains an opaque connectionId. Connection-scoped calls must reference it:

list_connections     {}
list_chats          { connectionId: "c-...", limit: 10 }
read_chat           { connectionId: "c-...", chatId: "ses_..." }
send_message        { connectionId: "c-...", chatId: "ses_...", message: "..." }
send_message_async  { connectionId: "c-...", chatId: "ses_...", message: "..." }
check_reply         { connectionId: "c-...", dispatchId: "d-..." }
connection_status   { connectionId: "c-..." }
disconnect_harness  { connectionId: "c-..." }

Connections and asynchronous dispatches live in the MCP process and do not survive a restart.

If disconnect_harness cannot close the connection, it returns an error and retains that connection ID for a retry. Calling disconnect_harness again with the same ID retries cleanup.

send_message defaults to a 300-second timeout and send_message_async to 900 seconds; both accept 1-3,600 seconds. check_reply.waitSeconds accepts 0-60 seconds. The send timeout covers connection-scoped validation, queueing, and the harness request. Codex timeout recovery can then take up to 3 seconds for interrupt acknowledgment and 3 seconds for terminal completion.

Canceling a foreground send_message aborts its OpenCode request or safely interrupts its correlated Codex turn. Canceling check_reply stops only that wait. A send_message_async dispatch remains independent after its dispatchId is returned.

The in-memory dispatch registry retains at most 100 records. Settled records expire after two hours and may be evicted earlier to admit new work; if all 100 records are active, a new asynchronous send is rejected before delivery starts.

Trusted Origins

Agents must not be allowed to send harness credentials to arbitrary URLs. Configure exact approved origins before starting Crossharness:

export CROSSHARNESS_ALLOWED_SERVER_URLS="http://127.0.0.1:4096/,ws://127.0.0.1:4500/"

connect_harness rejects origins not in this comma-separated allowlist. URLs containing user info, query parameters, fragments, or non-root paths are also rejected. HTTP redirects are never followed. At most one connection may bind a given harness, origin, and directory in one MCP process; the registry accepts up to 32 connections.

The standalone MCP server reads credentials from the harnesses' fixed environment variables. They are never accepted as tool arguments or printed:

• OpenCode: required OPENCODE_SERVER_PASSWORD and optional OPENCODE_SERVER_USERNAME
• Codex: CODEX_REMOTE_TOKEN

For remote servers, use TLS: https:// for OpenCode and wss:// for Codex.

OpenCode

Start an OpenCode server on a fixed URL:

OPENCODE_SERVER_PASSWORD="..." opencode serve --hostname 127.0.0.1 --port 4096

Crossharness uses only the official HTTP API:

• GET /global/health
• GET /session
• GET /session/:id
• GET /session/:id/message
• POST /session/:id/message

The connection directory is sent as a server-side query filter and verified against every selected session. Concurrent sends are passed directly to OpenCode; OpenCode owns session queuing. Crossharness does not intercept permissions and does not issue session-wide aborts. If a local HTTP wait times out, the server may still have queued or started the turn; Crossharness reports that uncertainty and never retries.

Codex

Start a Codex app-server on an explicit WebSocket URL:

codex app-server --listen ws://127.0.0.1:4500

For remote listeners, configure Codex WebSocket authentication and use wss://. Crossharness sends CODEX_REMOTE_TOKEN as a bearer token.

Each connection owns one initialized WebSocket and uses the official app-server JSON-RPC protocol:

• initialize followed by initialized
• thread/list with the connection directory as cwd
• thread/read with includeTurns
• thread/resume
• turn/start and correlated turn/item notifications
• turn/interrupt for a timed-out correlated turn

Turns on different threads may run concurrently. Sends to the same thread are sequenced so notification identity remains unambiguous. Each connection permits at most 100 queued or active sends, with at most 10 for one thread; a queued send can time out before delivery. Approval and elicitation requests are conservatively declined; unsupported server requests receive a JSON-RPC method-not-supported error instead of hanging.

If a Codex turn times out, Crossharness keeps the same-thread queue locked until turn/interrupt is acknowledged and turn/completed confirms terminal state. If the turn cannot be correlated, interruption is not acknowledged, or terminal state is not reported, the WebSocket connection is closed rather than risk overlapping turns or retrying an uncertain send.

Install

pnpm add -g @modelprofile.com/crossharness-mcp

# library use
pnpm add @modelprofile.com/crossharness-mcp

Requires Node.js 24 or newer.

Register the crossharness-mcp binary as a stdio MCP server in your client.

Library API

import {
  ConnectionRegistry,
  DispatchRegistry,
  CrossHarnessMcpServer,
} from '@modelprofile.com/crossharness-mcp';

const connections = new ConnectionRegistry({
  allowedServerUrls: ['http://127.0.0.1:4096/'],
  openCodeCredentials: {
    serverUrl: 'http://127.0.0.1:4096/',
    username: 'opencode',
    password: controllerOwnedPassword,
  },
});

const connection = await connections.connect(
  'opencode',
  'http://127.0.0.1:4096/',
  '/absolute/path/on/server',
);

const chats = await connections.get(connection.connectionId).listChats(10);
await connections.disconnect(connection.connectionId);

Connection closure is fail-closed and retryable. disconnect() retains ownership when a close fails, and another call with the same connection ID retries it. Overlapping close requests share the active close attempt. closeAll() permanently closes the registry to new connections, waits for every current close attempt, and retains failed connections for a later closeAll() retry. A single failure is rethrown directly; multiple failures are reported as an AggregateError.

openCodeCredentials is intended for an embedding application that owns the OpenCode server credential. The registry validates and copies it during construction. An injected password bypasses the environment credentials; an omitted username uses the protocol default opencode. Injected credentials are bound to their exact serverUrl, never included in connection metadata, and redacted from OpenCode HTTP response errors. Plain HTTP injection is accepted only for loopback hosts; use HTTPS for remote OpenCode servers. The standalone MCP server continues to read its credentials from fixed environment variables; credentials are never accepted as tool arguments.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.