codex-codebuddy-mcp

A minimal Python MCP server that lets Codex control CodeBuddy Code through its Agent Client Protocol (ACP) interface.

Features

• Session creation starts CodeBuddy and establishes the ACP session.

• One CodeBuddy process and ACP session per bridge session.

• Local launch and remote launch over OpenSSH stdio.

• Explicit bridge session IDs with MCP client ownership checks.

• Per-session model switching through ACP.

• At most two active CodeBuddy turns by default across the MCP server.

• Explicit permission approval modes: MCP elicitation or compatible two-step flow.

• Cancellation and deterministic child-process cleanup.

Related MCP server: cross_yapper

Requirements

• Python 3.11 or newer

• uv

• CodeBuddy Code with ACP support (codebuddy --acp)

• OpenSSH when using remote launch

Install and run

uv sync
uv run codex-codebuddy-mcp

The bridge has built-in defaults. In a source checkout, the repository-level config.yaml can override them:

max_read: 1048576 # 1 MiB, one ACP stdout/stderr line
max_output: 65536 # 64 KiB, one MCP result
max_concurrency: 2 # simultaneous active prompt turns
approval_mode: elicitation
timeout_seconds: 900 # default prompt/permission-turn timeout
startup_timeout_seconds: 60 # ACP initialize/session startup timeout
turn_cancel_timeout_seconds: 5 # wait for ACP turn cancellation
local_process_terminate_timeout_seconds: 5 # wait before local SIGKILL
remote_ssh_cleanup_timeout_seconds: 10 # wait for remote cleanup SSH command
stdout_overflow_retry_tolerance: 1 # oversized stdout turns tolerated before termination
stderr_tail_buffer_size: 80 # stderr lines retained for diagnostics

Installed wheels use the built-in defaults unless CODEX_CODEBUDDY_MCP_CONFIG names a YAML file. The KB, MB, and GB suffixes are accepted as binary multiples for backward compatibility; max_concurrency must be a unitless integer. The values can be overridden for an individual session by passing max_read and/or max_output to create_codebuddy_session. Timeout values are seconds. stdout_overflow_retry_tolerance is the number of oversized stdout responses that may be discarded while keeping the process available; 0 terminates the process on the first overflow. stderr_tail_buffer_size is measured in stderr lines. The prompt tools' timeout_seconds and the session creation tool's startup_timeout_seconds also accept per-call overrides. max_concurrency applies globally to all bridge sessions and is loaded when the MCP server starts.

Example Codex MCP configuration:

[mcp_servers.codebuddy]
command = "uv"
args = [
  "run",
  "--project",
  "/absolute/path/to/codex-codebuddy-mcp",
  "codex-codebuddy-mcp",
]

The MCP server writes protocol data to stdout and diagnostics to stderr.

Tools

create_codebuddy_session

Starts CodeBuddy, establishes the ACP session, and returns both a bridge_session_id and the codebuddy_session_id, along with the ACP-reported model_id and model_name. The model fields are returned when the session is created, not repeated on every prompt result. The bridge does not maintain a model allowlist. If CodeBuddy does not report model metadata, those two fields are null, rather than echoing an unverified model argument. If startup or session recovery fails, this call returns an error and does not leave a usable bridge session behind.

cwd and model_id are required. cwd sets the working directory for the CodeBuddy session. If it is present but empty or contains only whitespace, the bridge asks the user to enter a working directory through MCP elicitation. Clients without elicitation support receive an error that asks the caller to retry with a non-empty cwd. model_id must be non-empty and is passed to CodeBuddy as --model; do not repeat --model in codebuddy_args.

Local example arguments:

{
  "cwd": "/path/to/project",
  "model_id": "deepseek-v4.1-flash",
  "launch_mode": "local",
  "permission_mode": "auto",
  "approval_mode": "elicitation",
  "max_read": 4194304,
  "max_output": 65536
}

SSH example arguments:

{
  "cwd": "/home/dev/project",
  "model_id": "deepseek-v4.1-flash",
  "launch_mode": "ssh",
  "ssh_host": "dev-box",
  "ssh_args": ["-T"],
  "codebuddy_command": "/usr/local/bin/codebuddy"
}

SSH authentication uses the system ssh command, SSH config, and agent. Passwords are not accepted by this bridge. Values supplied through env are forwarded to CodeBuddy but should be treated as MCP tool input; prefer parent-process or remote host configuration for secrets.

approval_mode controls the bridge-to-MCP permission path. elicitation is the default and requires the MCP client to support elicitation; failures are returned as errors. compatible explicitly uses the two-step permission_required plus respond_codebuddy_permission flow. It does not silently fall back between modes.

By default the bridge reuses the CodeBuddy login already present on the target machine. If no login is available it returns an authentication-required error. auth_method_id can explicitly request external, internal, iOA, or selfhosted authentication; CodeBuddy may open or wait for its normal login flow, so use this only when interactive authentication is intended.

permission_mode defaults to auto and is passed to CodeBuddy as --permission-mode auto. The supported values are acceptEdits, bypassPermissions, default, plan, dontAsk, and auto. The bridge allows max_concurrency active turns at the same time across sessions; turns in one ACP session remain serialized. max_read controls the asyncio subprocess stream limit used for reading each ACP stdout/stderr line. Its YAML default is 1048576 bytes (1 MiB). Increase it when a single ACP JSON line can be larger; it must be a positive integer. On the first stdout overrun, the bridge discards that response, cancels the current turn, and keeps the process available so the caller can request a compressed answer. Changing max_read requires creating a new bridge session. A successful turn clears the overrun count; once stdout_overflow_retry_tolerance is exceeded, the process is terminated. Oversized stderr lines are discarded without stopping the session. max_output controls the MCP result threshold and defaults to 65536 bytes (64 KiB).

The concurrency limit applies to active session/prompt turns, including turns waiting for a permission decision. It does not limit the number of started CodeBuddy processes. A third session may be created and remain ready, but its prompt waits for a turn slot and fails when its timeout expires. In compatible approval mode, an unanswered permission request is cancelled after the calling tool's timeout_seconds, which releases its global turn slot. Operations within one bridge session are serialized by that session's lock.

The registry is in memory. Restarting the MCP server loses bridge session IDs, owner bindings, locks, pending permissions, in-flight buffers, and process handles. Persist the returned codebuddy_session_id if recovery is needed; a new bridge session can pass it as resume_session_id. The bridge cannot discover old CodeBuddy sessions automatically.

switch_codebuddy_model

Switches the model for an existing bridge session between turns:

{
  "bridge_session_id": "...",
  "model_id": "deepseek-v4.1-flash"
}

The bridge sends ACP session/set_model with the bound CodeBuddy session. CodeBuddy must acknowledge the change; ACP errors are returned directly and do not change the bridge's recorded model. A successful call returns model_id and model_name once, together with both session IDs. Switching while a prompt or permission request is active is rejected; finish or cancel that turn first.

prompt_codebuddy

Sends a text prompt to the already-started CodeBuddy session. A completed turn returns the final text, stop reason, tool summaries, and CodeBuddy session ID.

max_output controls the maximum UTF-8 byte size of every prompt result and defaults to 65536. When the serialized result is larger, the bridge writes the complete JSON result to a 0600 file in the local temporary directory and returns output_path, output_bytes, and text_available_in_file=true instead of embedding the large text in the MCP response. Permission metadata remains in the compact response so the caller can continue the same turn; the caller can read the complete result from that path with its local file tools. MCP/JSON-RPC does not define one universal maximum, but the calling Codex or harness may enforce a per-message limit, so a conservative max_output is useful for long reports. The bridge removes tracked output files when their bridge session closes or the server shuts down.

For reports that exceed the file threshold, the same bridge session remains available for follow-up prompts and additional sections.

With approval_mode="compatible", the tool returns:

{
  "status": "permission_required",
  "permission": {
    "request_id": "...",
    "tool_name": "Bash",
    "raw_input": {"command": "..."},
    "options": [
      {"kind": "allow", "name": "Allow", "optionId": "allow"},
      {"kind": "reject", "name": "Deny", "optionId": "deny"}
    ]
  }
}

respond_codebuddy_permission

Pass the exact request_id and one of the returned optionId values. The call continues the same CodeBuddy turn and may complete or return another permission request. It also accepts max_output with the same file externalization behavior.

cancel_codebuddy_turn and close_codebuddy_session

Completing a prompt does not close CodeBuddy. Cancellation keeps the CodeBuddy process available. Closing cancels active work, terminates the local process or SSH channel, and removes the bridge session. On SSH, the bridge records a unique remote PID file and performs a second SSH cleanup command that terminates that process group. The remote shell uses set -m, starts CodeBuddy as a monitored job, and waits for it so the SSH stdio channel stays connected for ACP responses. This handles CodeBuddy processes that outlive the SSH channel; abrupt network loss or a remote process that ignores termination cannot be guaranteed by the local client.

Tests

Run the default suite, including a real installed CodeBuddy ACP handshake:

uv run pytest

The handshake starts the actual codebuddy-code binary, validates ACP initialization and login state handling, and creates an ACP session when the installed CLI is already authenticated. It does not send a model prompt or consume model quota. A second real startup test verifies that the default permission mode passed to CodeBuddy is auto, rather than plan. These tests skip only when codebuddy is not installed.

An opt-in end-to-end model test is also provided. It sends a real prompt and may consume quota:

RUN_CODEBUDDY_MODEL_TEST=1 uv run pytest -m model

The real permission-forwarding test is parameterized over both supported forwarding modes. It prompts CodeBuddy to request approval for a harmless printf through Bash, verifies either the compatible two-step response or MCP elicitation, selects an allow option, and checks that the same turn completes. It is separately opt-in because each mode sends a model prompt and executes the approved command:

RUN_CODEBUDDY_PERMISSION_TEST=1 uv run pytest \
  tests/test_server.py::test_real_codebuddy_permission_request_is_forwarded

Run static checks:

uv run ruff check .