Agent Interop Runtime MCP server

Agent Interop Runtime

Agent Interop Runtime is a local MCP server for connecting supported coding agents through their native local interfaces.

It keeps provider sessions separate and adds a safe coordinator for directed messages between them. It does not merge provider accounts. It does not place an agent inside a normal ChatGPT web conversation. It does not bypass a provider login or approval screen.

What works

The runtime can do the following when the matching provider is installed and available.

• Discover providers and their real capability status
• Discover native sessions without changing their identity
• Create and resume supported native sessions
• Send prompts through the provider protocol
• Cancel work when the provider exposes cancellation
• Read provider events and native diffs when available
• Read approved local project files with traversal and size protection
• Store work evidence and verification results
• Route directed messages through a durable local conversation record

The shared conversation record is not a shared native transcript. Each provider keeps its own context. A message sent through the coordinator is recorded with a sender, recipient, reply link, and delivery receipt. A queued receipt means that transport accepted the message. It does not mean that the provider completed the task.

Requirements

The runtime supports Windows macOS and Linux.

Use Node 20 through Node 26. The published package includes the native PTY dependency required by Freebuff CLI mode.

Freebuff support requires one of these local installations.

• Freebuff Desktop installed and signed in
• Freebuff CLI installed and signed in
• Both may be installed. Desktop is preferred unless CLI mode is explicitly selected.

The other providers have their own requirements.

• OpenCode requires the OpenCode CLI; the runtime can start and manage a local server automatically
• Codex requires the Codex app server command
• Claude Code requires the Claude ACP executable
• Cursor requires the Cursor agent ACP command

The runtime never fabricates an available provider. Run the doctor command to see the exact reason for an unavailable provider.

Install from npm

The simplest installation uses pnpm.

pnpm add --global agent-interop-runtime
agent-interop-runtime doctor

You can also use the package without a global install.

pnpm dlx agent-interop-runtime@0.2.18 doctor
pnpm dlx agent-interop-runtime@0.2.18 serve

The version is pinned in the examples so a host does not silently change behavior during startup. Update the version deliberately after reviewing a release.

Configure a local MCP client

Build from source when developing the project.

pnpm install
pnpm build
node dist/src/cli.js doctor

The local Codex configuration uses this shape.

[mcp_servers.agent_interop]
command = 'node'
args = ['C:\path\to\agent-interop-runtime\dist\src\cli.js', 'serve']
enabled = true

The installer can add or repair this entry.

pnpm dlx agent-interop-runtime@0.2.18 install
pnpm dlx agent-interop-runtime@0.2.18 install --write

The write command preserves unrelated Codex configuration, makes one backup, uses an atomic replacement, and refuses malformed existing content. Set CODEX_HOME when Codex uses a nonstandard configuration directory.

Restart the local MCP client after changing its configuration.

The installer is explicit by design. npm installation does not change a user configuration through a postinstall hook.

Freebuff Desktop

Desktop mode is selected automatically when the local orchestrator can be reached.

The runtime discovers the current loopback port from supported readiness files, local logs, and local process data. It then calls the local projects route.

GET /api/projects

Writes require the current launch authorization header.

x-freebuff-launch-id

Shortened. The full README is on GitHub.