agent-shuttle-mcp
This MCP server delegates prompts to locally configured agent harnesses (Antigravity, Codex, and any profile from BRIDGE_AGENTS_JSON) and reads their live models/quotas without spending a model turn.
ask_agent(agent_id, prompt)— send a task to a configured agent profile; optionalmodel,reasoning_effort, andtool_policy.get_agent_info(agent_id)— read capabilities and quota info for a configured profile, no agent turn.ask_antigravity(prompt)— delegate to Antigravity; optionalworkspacestarts an isolated temporary Bridge, plusmodel,reasoning_effort,tool_policy, andturn_timeout_seconds(default 300).ask_codex(prompt)— delegate to Codex, withmodelandreasoning_effortselecting its thread settings.get_antigravity_info(workspace?)— read Antigravity's current models, effort options, and account quota without an agent turn.get_codex_info()— read Codex's current models, supported efforts, and account quota without an agent turn.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agent-shuttle-mcp ask Codex to explain the project structure"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Agent Shuttle
Russian version / Русская версия
Agent Shuttle is a Python library and MCP server for working with local Antigravity, Codex, Claude Code, OpenCode, and configured ACP agents. Delegate research, code reviews, implementation and second opinions using the harnesses' existing local authentication.
Use the Python API in your application, or connect the MCP server to your AI assistant. Both interfaces manage local agent tasks, multi-turn sessions, live model catalogs, account quotas and tool-policy guarantees. A2A 1.0 JSON-RPC is the peer protocol. Available research tools, including web access, depend on the selected harness and policy.
Python:
uv add agent-shuttle; useTaskManager,ShuttleClient, orconnect_harness.MCP:
uv tool install agent-shuttle; connectagent-shuttle mcporagent-shuttle-mcp.Discovery and setup: connect, diagnose, use Docker Gateway, or prepare a registry release.
File editing tasks can use isolated Git worktrees with explicit change application.
Supported Agent Harnesses
Harness | Primary Integration Mechanism | Auth & Model Access | Key Features |
Codex | Official | Local Codex App Server sign-in | Sandboxes ( |
Antigravity | Official | Signed-in Antigravity account | Real-time models, efforts, and |
OpenCode | Managed local HTTP server ( | Local Ollama or cloud providers | Configured via JSON profile, fine-grained tool policies ( |
Claude Code | Managed CLI in print mode ( | Local Ollama endpoint or Anthropic | Configured via JSON profile, isolated temporary session configs, resume support, safe mode vs full access. |
Configured ACP agent | Agent Client Protocol over local stdio | Agent's own account and model configuration | Register a command in a JSON profile; streamed updates, cancellation, and capability-gated session loading. Tool policies are advisory. |
Related MCP server: pokeclaw
Installation
Agent Shuttle runs on Windows, Linux, and macOS. For the command-line tools and MCP server, install uv first; uv can obtain a compatible Python automatically.
Install the commands and MCP server
uv tool install agent-shuttle
uv tool dir --binThe last command shows where uv placed agent-shuttle-mcp (with .exe on Windows); use its absolute path in your MCP client's configuration. To use agent-shuttle directly in a shell, run uv tool update-shell if the command is not on PATH, then open a new shell.
To check local harness availability, run agent-shuttle discover; it does not authenticate or send a model request. agent-shuttle doctor <agent> --smoke checks a real model turn when needed. MCP already provides ask_agent for supported harnesses and configured profiles.
Use the Python library in another project
uv add agent-shuttleuv tool install isolates the tool from your project's Python environment. Install Agent Shuttle as a project dependency when your code imports agent_shuttle.
Install from Local Checkout
You can install Agent Shuttle directly from its repository checkout into your project's virtual environment:
# Create and activate your virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1
# Install in standard or editable mode
pip install C:\path\to\agent-shuttle
# or editable mode during development:
# pip install -e C:\path\to\agent-shuttleOnce installed, the CLI tools (agent-shuttle, agent-shuttle-mcp) and Python API (agent_shuttle) are fully accessible inside that virtual environment. The original checkout directory does not need to stay in place for runtime imports. Version 0.8 uses Shuttle names throughout the Python API, environment, HTTP routes, and A2A metadata. See connection and release guidance before restarting existing servers.
The distribution has one Python package: src/agent_shuttle/. This is the standard src layout; there is no second implementation or compatibility package.
Quickstart
Install the MCP server, then give your MCP client its absolute executable path:
uv tool install agent-shuttle
uv tool dir --binPoint your MCP client's command at agent-shuttle-mcp in the printed directory. MCP starts a local A2A peer when a request needs one; there is no separate server startup step. See the getting started guide for MCP configuration and harness setup.
For a persistent server, run agent-shuttle serve codex --workspace . --port 8765 (or serve antigravity on port 8766) in a terminal and stop it with Ctrl+C.
Minimal Examples
1. Python API
import asyncio
from pathlib import Path
from agent_shuttle import ShuttleClient, HarnessLaunch, connect_harness
async def main():
client = ShuttleClient()
# Query live model catalog and quota information
info = await client.info("http://127.0.0.1:8766")
print("Selected model:", info["capabilities"]["selected_model"])
# One-shot task
result = await client.ask(
"http://127.0.0.1:8766",
"Explain the project structure and list entry points.",
model="gemini-3.8-flash-medium",
reasoning_effort="medium",
)
print(f"[{result.state}] Task {result.task_id}:\n{result.text}")
# Persistent multi-turn session (preserves conversation context)
async with client.session(
"http://127.0.0.1:8765",
model="gpt-5.6-terra",
reasoning_effort="high",
) as session:
step1 = await session.ask("What database migrations are pending?")
step2 = await session.ask("Generate SQL to apply the first migration.")
print("Step 2 response:", step2.text)
print("Step 2 token usage:", step2.usage)
# Managed peer lifecycle: reuse existing server or start a temporary one
launch = HarnessLaunch(
name="antigravity",
url="http://127.0.0.1:8766",
workspace=Path.cwd(),
)
async with connect_harness(launch) as conn:
print("Connected to:", conn.url, "(spawned temporary:", conn.started, ")")
asyncio.run(main())2. Command-Line Interface (CLI)
# Discover locally installed harnesses without starting models
agent-shuttle discover
# Check installation and connection without a model turn
agent-shuttle doctor
agent-shuttle doctor --profile .\examples\opencode-ollama.json
# After fixing a reported issue, verify one real turn (uses model tokens)
agent-shuttle doctor codex --smoke
# Start an A2A server for Codex
agent-shuttle serve codex --workspace . --port 8765
# Start an A2A server for Antigravity (CLI mode)
agent-shuttle serve antigravity --workspace . --port 8766
# Start an A2A server from a profile (OpenCode, Claude Code or ACP)
agent-shuttle serve profile --profile .\examples\opencode-ollama.json --workspace . --port 8767
# Query server capabilities, models, and quota limits
agent-shuttle info http://127.0.0.1:8765
# Send a task from the command line
agent-shuttle ask http://127.0.0.1:8765 "Summarize recent changes" --model gpt-5.6-terradoctor reports installation, connection and turn verification separately. Its default run checks built-ins and local profiles registered in AGENT_SHUTTLE_AGENTS_JSON; missing optional runtimes are skipped. OpenCode and Claude Code need a JSON profile for connection checks. --json provides the same report for scripts. Exit codes are 0 for passed checks, 1 for a failed target or smoke turn, and 2 for invalid invocation or configuration. --smoke requires one target and uses enforced no_tools (or Codex read_only); ACP smoke is rejected because ACP cannot enforce those restrictions.
Register an ACP agent
Copy examples/acp-worker.json, set command to the installed agent's ACP launch command, and set workspace to the project directory. command is an argument array; it is never run through a shell. provider, default_model, allowed_models, and reasoning_efforts are optional for ACP. Without allowlists, an explicit model or effort may select any variant advertised in the session's ACP config options; configured allowlists narrow those choices.
agent-shuttle discover --profile .\examples\acp-worker.json
agent-shuttle serve profile --profile .\examples\acp-worker.json --port 8768
agent-shuttle info http://127.0.0.1:8768
agent-shuttle ask http://127.0.0.1:8768 "Explain this project" --tool-policy read_onlyFor MCP managed startup, map an arbitrary ID to the profile in AGENT_SHUTTLE_AGENTS_JSON:
{"my-acp": {"harness": "acp", "profile": "C:/profiles/my-acp.json"}}ACP discovery checks the command without starting the agent. info performs the ACP handshake and reports negotiated capabilities without sending a model prompt. ACP policies are advisory: results include a warning, and read_only_tools remains false because the agent may use tools outside client permission requests. Use a verified external sandbox when an enforceable restriction is required.
3. Model Context Protocol (MCP)
Start the stdio MCP server:
agent-shuttle-mcp
# or: python -m agent_shuttle.mcp_serverAvailable MCP tools:
ask_agent(agent_id, prompt, model?, reasoning_effort?, tool_policy?, workspace?): Reuses a matching local A2A server or starts a temporary one. Built-in IDs arecodex,antigravity,opencode, andclaude_code; configured ACP IDs require a JSON profile inAGENT_SHUTTLE_AGENTS_JSON.get_agent_info(agent_id, workspace?): Fetches live models and quotas, starting a temporary server if needed.ask_antigravity(prompt, model?, reasoning_effort?, workspace?, tool_policy?, turn_timeout_seconds=300): Starts an Antigravity server if one is not running.ask_codex(prompt, model?, reasoning_effort?, workspace?): Starts a Codex server if one is not running.get_antigravity_info(workspace?)&get_codex_info(): Read live capabilities and quota without burning model turns.submit_task(agent_id, prompt, model?, reasoning_effort?, tool_policy?, workspace?, request_id?): Start a long task and return its ID immediately.check_task(task_id),wait_task(task_id, timeout_seconds?),cancel_task(task_id): Inspect, wait for, or stop a task.get_result(task_id, cursor?, limit?),get_transcript(task_id, cursor?, limit?): Read bounded pages of output and history.get_events(task_id, cursor?, limit?),get_event_page(task_id, seq, cursor?, limit?): Read Shuttle's ordered event journal and full data for a truncated event. Savetotal_sizeto poll after the current end.
Key Concepts
Harness Discovery
Run agent-shuttle discover (or discover_harnesses() in Python) to inspect local executables without launching processes or loading weights. It checks PATH and platform-specific standard installation directories (%LOCALAPPDATA%\agy\bin, npm global directories, etc.). Custom paths can be specified via environment variables (AGENT_SHUTTLE_AGY_COMMAND) or CLI flags (--agy-command, --opencode-command, --claude-command).
Model & Reasoning Selection
Model parameters are passed as A2A metadata keys (agent_shuttle.model, agent_shuttle.reasoning_effort):
Antigravity: Reasoning effort is embedded in model IDs (e.g.
gemini-3.8-flash-medium). If both--modeland--effortare passed, they must match.Codex: Model and reasoning effort are configured independently according to the catalog returned by
get_codex_info.OpenCode & Claude Code: Profiles define
allowed_modelsand optionalreasoning_efforts(such as model variants for Ollama or CLI flags).
Workspaces & Session Isolation
Every server binds to a strictly validated, canonical workspace directory.
connect_harness()verifies that an existing server's workspace matches the caller's target workspace before reusing it.Sessions:
ShuttleSessionmaintains a stateful conversation across multipleask()calls. Conversation settings (model, effort, tool policy) are pinned at session creation and cannot be changed mid-session. Idle sessions are cleaned up automatically after 30 minutes.Library task lifecycle:
TaskManagerruns agents directly from Python, with no A2A or MCP server. It owns task IDs, sessions, a SQLite event journal, cancellation, result paging, preferences, and interruption recovery. A2A projects the same task ID and result through its protocol; MCP continues to reach those tasks through managed A2A peers. See the Python API.Remote task lifecycle:
ShuttleClient.submit()returns a remoteTaskHandleimmediately. Usestatus(), boundedwait(timeout), liveevents(), Shuttle-onlyevents_page()andevent_page(),result_page(),transcript(),result(), orcancel(); reopen a task by ID withclient.task(url, task_id). A wait timeout does not stop the agent. An optional UUIDrequest_iddeduplicates retried submissions. Standalone servers can persist tasks with--task-db; MCP task tools do this automatically in the workspace's.agent-shuttledirectory. Completed results survive restart; interrupted work is marked failed without replay. See the API reference.
Safety & Tool Policies
Agent Shuttle defines four standardized tool policies:
no_tools: Disables tool invocations entirely.read_only: Permits non-mutating search and file reading.workspace_write: Allows editing files within the designated workspace.full_access: Explicitly unclamps all tool restrictions and approval prompts.
For configured ACP agents, these policies are advisory. Agent Shuttle checks ACP permission requests but cannot prevent an agent from acting outside them. See the permissions guide.
full_access grants the worker unrestricted tool access for that task. --agy-dangerously-skip-permissions enables that capability for the Antigravity server. Keep servers on loopback. Antigravity's explicit scoped read_only policy is enforced by its verified PreToolUse hook; an implicit/default CLI policy does not provide the same guarantee.
Testing
Agent Shuttle provides a comprehensive offline test suite using fake backends that execute without network access, credentials, or model quota consumption:
GitHub Actions runs this same suite on Windows, Ubuntu Linux, and Apple Silicon macOS (macos-15), each with Python 3.11 and 3.12. The process smoke uses only a local Python worker and checks process-tree cleanup; no agent CLI or account is needed.
python -m unittest discover -s tests -vLive integration tests against real models are separate, opt-in checks and are not part of the six CI jobs. They can be executed by specifying target environments (e.g. AGENT_SHUTTLE_LIVE_OLLAMA_MODEL=qwen3.5:9b or AGENT_SHUTTLE_LIVE_AGY_FULL_ACCESS=1). See CONTRIBUTING.md for full instructions.
Documentation Index
Available Tools
19 toolsapply_task_changesB
Explicitly apply reviewed changes if touched source files still match the base.
Inputs: task_id (required), expected_revision (required), allow_partial.
ask_agentA
Delegate research, code review, implementation or a second opinion to a local AI agent: Antigravity (antigravity), Codex (codex), OpenCode (opencode), Claude Code (claude_code), or an agent_id from list_agents. Делегирование: исследование, ревью, реализация, второе мнение. Use for an actual request to have another agent perform work. Answer general explanations and advice directly; mentioning an agent or a second opinion alone does not request delegation. Shuttle manages local servers automatically. Inspect get_agent_info before selecting an enforceable tool policy; research including web access depends on that agent's capabilities. For Antigravity web research choose web_research when advertised; read_only allows local files only. Preserve the user's explicit agent and model. Use submit_task for long work.
Inputs: prompt (required), agent_id (required), model, workspace, +2 more.
ask_antigravityC
Delegate to Antigravity. Default: read_only; choose workspace_write for file edits.
Scoped policies enforce native file tools and block shell/MCP/subagents. Servers and per-conversation permission hooks are managed automatically.
Inputs: prompt (required), model, workspace, tool_policy, +2 more.
ask_codexC
Delegate to Codex, launching its A2A server when absent. Omit model unless requested.
Inputs: prompt (required), model, workspace, tool_policy, +1 more.
cancel_taskB
Stop the delegated task and wait for backend cleanup; repeated cancellation is safe.
Inputs: task_id (required).
check_taskC
Read the current task snapshot without waiting for the worker.
Inputs: task_id (required).
discard_task_changesC
Explicitly delete an isolated task's saved change and owned worktree.
Inputs: task_id (required).
get_agent_infoA
Inspect live models, account quota and enforceable tool policies for Antigravity, Codex, Claude Code, OpenCode or a configured ACP agent before delegating research, review, implementation or a second opinion. Manages the local server automatically. This checks live metadata without a model turn; use list_agents for offline inventory.
Inputs: agent_id (required), workspace.
get_antigravity_infoB
Read Antigravity's current models, effort options and account quota without an agent turn.
Inputs: workspace.
get_codex_infoA
Read Codex's current models, supported efforts and account quota without an agent turn.
Inputs: workspace.
get_event_pageC
Read full JSON data for a journal event with data_truncated=true.
Inputs: seq (required), task_id (required), limit, cursor.
get_eventsB
Read Shuttle's ordered event journal. Save total_size to poll after the current end.
Inputs: task_id (required), limit, cursor.
get_resultC
Read a bounded result page; follow next_cursor until it is null.
Inputs: task_id (required), limit, cursor.
get_task_changesB
Describe an isolated task's saved changes; no files are modified.
Inputs: task_id (required).
get_task_diffC
Read a bounded page of an isolated task's Git binary patch.
Inputs: task_id (required), limit, cursor.
get_transcriptB
Read a page of A2A task history and artifacts; status updates may be absent.
Inputs: task_id (required), limit, cursor.
list_agentsA
Discover local Antigravity, Codex, Claude Code, OpenCode and configured ACP agents for delegation, research, code review, implementation and second opinions. Lists agent_id, command availability and configuration errors without starting agent processes, contacting models or verifying authentication. Use get_agent_info for live readiness, models and tool policies. Поиск агентов для делегирования задач. Use when asked to discover actual available local agents or while preparing authorized delegation. General explanations and advice about agents or second opinions do not require an inventory of the user's installed agents.
Inputs: no named parameters.
submit_taskA
Delegate research, code review, implementation or a second opinion to a local AI agent: Antigravity (antigravity), Codex (codex), OpenCode (opencode), Claude Code (claude_code), or an agent_id from list_agents. Делегирование: исследование, ревью, реализация, второе мнение. Use for an actual request to have another agent perform work. Answer general explanations and advice directly; mentioning an agent or a second opinion alone does not request delegation. Shuttle manages local servers automatically. Inspect get_agent_info before selecting an enforceable tool policy; research including web access depends on that agent's capabilities. For Antigravity web research choose web_research when advertised; read_only allows local files only. Preserve the user's explicit agent and model. Use submit_task for long work. Returns a task ticket immediately; use check_task/wait_task, then get_result. Reuse request_id when retrying submission.
Inputs: prompt (required), agent_id (required), model, workspace, +4 more.
wait_taskC
Wait within a separate budget; expiry returns a snapshot and never cancels work.
Inputs: task_id (required), timeout_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Four tools perform delegation with near-identical purposes: ask_agent, submit_task (whose description is literally identical plus one sentence), ask_antigravity, and ask_codex. Likewise get_agent_info, get_codex_info, and get_antigravity_info overlap, leaving the agent to guess whether to use the generic or per-backend variant. The read-side tools (get_result, get_transcript, get_events, get_event_page) are distinguishable only by careful reading.
Almost everything follows a verb_noun snake_case pattern (get_result, submit_task, check_task, wait_task, cancel_task, list_agents, get_task_diff). Minor deviations exist: ask_antigravity/ask_codex drop the '_agent' suffix used by ask_agent, and apply_task_changes/discard_task_changes use a three-part noun phrase.
At 19 tools the surface is heavy and includes clear redundancy: ask_antigravity/ask_codex duplicate ask_agent, and get_codex_info/get_antigravity_info duplicate get_agent_info. The task lifecycle (submit/check/wait/cancel/diff/apply/discard) legitimately needs several tools, but a leaner set would be easier to navigate.
The domain is well covered end-to-end: discovery (list_agents), capability inspection, sync and async delegation, polling, waiting, cancellation, paginated results, transcripts, event journal, and diff review/apply/discard. Gaps are minor, e.g. no explicit follow-up message or task listing/cleanup operation.
Maintenance
Related MCP Connectors
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Build and manage AI-native customer support agents from Claude or any MCP client.
Related MCP Servers
- AlicenseAqualityDmaintenanceWraps Claude Code as tools for MCP clients, enabling autonomous coding tasks via a 4-tool lifecycle with session management, async polling, and permission controls.457 npm21MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to spawn and control Codex CLI and Claude Code sessions on the host machine, with session management and filesystem access.4MIT
- FlicenseNot gradedqualityBmaintenanceAgent orchestration system that runs coding-agent sessions (Claude Code, Codex) with policy mediation and exposes tools via MCP.-
- AlicenseBqualityBmaintenanceEnables launching and supervising local Codex and Claude Code agent sessions and one-shot tasks, exposing run, list, stop, and output operations over MCP with session-scoped permissions and sandbox controls.2264 npm1MIT