📟 codemcp 📟

codemcp exposes agentic coding through the official harnesses of Codex and Claude Code as a small mcp server. runs are asynchronous: they execute detached, results are collected by polling — safe behind any transport timeout.

installation

composer require vielhuber/codemcp

Related MCP server: claude-code-mcp

setup

.env in the project root (only for mcps via http):

MCP_TOKEN=

usage

every function below is also exposed 1:1 as an mcp tool of the same name.

$code = codemcp::create();

$session = $code->start(
    prompt: 'Fix the failing tests.',
    workdir: '/app',
    provider: 'claude',
    model: 'claude-opus-4-8',
    effort: 'high'
);

$session = $code->wait(
    session_id: $session['session_id'],
    timeout: 120
);

$session = $code->status(
    session_id: $session['session_id']
);
$code->status();

$session = $code->continue(
    session_id: $session['session_id'],
    prompt: 'Now also fix the linter warnings.'
);

$session = $code->stop(
    session_id: $session['session_id']
);

$providers = $code->providers();

When workdir is omitted, each new session gets a random isolated directory under sys_get_temp_dir()/codemcp/. An explicit directory is created recursively when it does not exist, so new projects start in their final workspace and retain folder continuity. A running session for that folder is reused; otherwise Codemcp resumes the most recently active native Codex or Claude session and creates a new thread only when no folder history exists. model and effort are optional; when omitted, the selected coding agent uses its own defaults. Supported explicit effort values are minimal, low, medium, high and xhigh.

When start or continue submits a prompt to an existing session, the immediate response has status queued. queued_prompt and queue_position describe the new submission, while previous_prompt and previous_result expose the prior context without presenting it as the new result. session_status contains the underlying runtime state. Subsequent wait and status calls return the regular session status (running, completed, error or stopped) and the new final answer in last_content.

Long-running agents are limited by inactivity, not total runtime. MCP progress events and command output reset the internal inactivity timeout, so an active run can continue beyond 30 minutes while a stalled run is still terminated.

tests

./vendor/bin/phpunit