llm-provider-mcp

CI Release License: MIT

Delegate coding work between Claude Code, Codex, Cursor Agent, and Pi.

llm-provider-mcp is a local MCP server for asynchronous coding-agent delegation. A Codex or Claude Code session can start work in another coding CLI, receive a job ID immediately, continue its own work, and collect the delegated result later.

Delegated agents run locally in detached tmux sessions using their existing logins, model access, filesystem permissions, and the host's current trusted project directory.

Claude Code delegating a background coding task to Cursor

This is a real Claude Code to Cursor Composer 2.5 run: the job completed in 28 seconds and Claude independently verified the diff and uncached test result. See the reproducible demo and sanitized transcript.

Claude Code delegating a background coding task to Codex GPT-5.6 Sol

This second real run delegates from Claude Code to Codex CLI with gpt-5.6-sol. Codex completed the bounded fix in 36 seconds, and Claude independently inspected the diff and reran the test. The run used Codex CLI 0.145.0-alpha.4; stable 0.144.1 rejected Sol during its rollout.

Quick Start

Requirements:

• macOS or Linux
• tmux 3.x or newer
• Codex or Claude Code as an MCP host
• At least one authenticated target: Cursor Agent, Pi, Codex, or Claude Code

From the project where you want to use delegation, run:

curl -fsSL https://raw.githubusercontent.com/manishiitg/llm-provider-mcp/main/scripts/install-mcp.sh | sh

The interactive setup detects installed CLIs, lets you select multiple hosts and targets, verifies authentication, registers the MCP server only for the current project, and installs a small delegation skill.

The server is also published in the official MCP Registry as io.github.manishiitg/llm-provider-mcp.

Start a new Codex or Claude Code session in that project and ask naturally:

Delegate the failing authentication test to Cursor using composer-2.5.
Keep working here and check the delegated job when it is ready.

The host receives a response shaped like:

{
  "job_id": "job_03070f8a2626b50ace1a67a463db9b4d",
  "provider": "cursor-cli",
  "status": "queued",
  "poll_after_seconds": 15,
  "next_tool": "get_coding_agent_job"
}

See Installation for manual and security-conscious installation options.

Why Use It

• Use a stronger model for an independent review or difficult implementation.
• Route small work to a faster or lower-cost model without leaving the host.
• Access Cursor, Gemini, OpenRouter, MiniMax, GLM, and Kimi models from Codex or Claude Code.
• Run independent delegations concurrently without blocking the host session.
• Inspect a live terminal tail or attach directly to tmux when human attention is needed.
• Keep credentials with the native CLIs instead of copying API keys into the MCP server.

Supported Coding CLIs

The setup wizard currently registers Codex and Claude Code as hosts. Cursor and Pi can use the same stdio MCP server through manual project configuration. All four CLIs can run as local delegation targets.

Gemini CLI and Antigravity CLI remain available only as deprecated Go-library compatibility integrations and are not offered during new MCP setup.

See Providers and models for selectors, authentication commands, and provider-specific behavior.

How Delegation Works

sequenceDiagram
    participant H as Claude Code or Codex
    participant M as llm-provider-mcp
    participant J as Job worker
    participant T as Cursor, Pi, Codex, or Claude
    H->>M: delegate_coding_agent(task, provider, working_dir)
    M->>J: Persist and queue job
    M-->>H: job_id immediately
    J->>T: Start detached tmux session
    H->>H: Continue host work
    H->>M: get_coding_agent_job(job_id)
    M-->>H: Progress, terminal tail, or final result

1. The host passes its current trusted project and a bounded task.
2. The server validates the provider and workspace, then persists the job in SQLite.
3. A detached worker launches the target CLI in tmux.
4. The host polls after the recommended interval while continuing other work.
5. The host reviews the final result and verifies any workspace changes.

Polling is the current completion mechanism. MCP task notifications are planned after behavior is consistent across supported hosts.

See Delegation workflow and Architecture for the complete lifecycle.

MCP Tools

The server exposes five tools:

Running jobs include a tmux attach command for direct human inspection. get_coding_agent_job can also return a bounded, ANSI-cleaned terminal tail.

CLI Commands

llm-provider-mcp setup
llm-provider-mcp doctor
llm-provider-mcp models cursor-cli
llm-provider-mcp models pi-cli --json
llm-provider-mcp uninstall

setup, doctor, and uninstall are designed to work without additional arguments. Run llm-provider-mcp --help for automation flags.

Security And Trust

• The MCP server and delegated CLIs run on the local machine.
• Credentials remain owned by each native CLI and are never collected by setup.
• Setup writes project-local MCP and skill configuration only after showing the exact paths.
• The host supplies its current trusted project as working_dir; users are not asked to enter it for every job.
• Detached agents use unattended provider-specific policies so they do not block on invisible approval prompts.
• LLM_PROVIDER_MCP_WORKSPACE_ROOTS can restrict accepted working directories, but it is not a process sandbox.

Pi currently has no hard workspace sandbox, so its shell and file tools retain the permissions of the local user. Do not delegate untrusted prompts or repositories to Pi.

Read Security and trust before enabling unattended delegation in sensitive repositories.

Current Limitations

• macOS and Linux only; Windows is not currently supported.
• tmux is required for delegated execution and live inspection.
• Completion is polling-based rather than pushed to the host.
• Host auto-registration currently supports Codex and Claude Code.
• Target model availability depends on the user's existing CLI account.
• A delegated agent can modify the working tree; the host must review and test those changes before accepting them.

Documentation

• Installation
• Delegation workflow
• Providers and models
• Security and trust
• Architecture
• Troubleshooting
• Go compatibility library
• Roadmap

Go Compatibility Library

This repository also contains the Go provider module used by MCP Agent and MCP Agent Builder. Its existing module path remains intentionally unchanged:

go get github.com/manishiitg/multi-llm-provider-go@latest

The general provider APIs remain supported for downstream compatibility, but the primary product surface of this repository is llm-provider-mcp. See the Go compatibility library documentation.

Development

make build-mcp
go test ./...
golangci-lint run --timeout=5m ./...

The CI suite also compile-checks MCP Agent and MCP Agent Builder against the current checkout to prevent accidental public-API breakage.

See CONTRIBUTING.md before opening a pull request. Report security issues using SECURITY.md, not a public issue.

License

MIT