AgentBridge Nexus MCP Server

Python MCP server that exposes AgentBridge backend actions as tools for AI coding agents.

Status

The backend/MCP terminal MVP is implemented and live-tested. The package currently provides:

• backend HTTP client
• testable tool functions
• MCP FastMCP entrypoint
• core lifecycle, artifact, coordination, audit, memory, and validation tools

Environment

Set these before running the MCP server:

export AGENTBRIDGE_API_URL="http://localhost:8000"
export AGENTBRIDGE_AGENT_KEY="abk_your_agent_key"

AGENTBRIDGE_AGENT_KEY should be one of the keys printed by:

cd services/api
.venv/bin/python scripts/seed_dev.py --apply

Tools

• agentbridge_heartbeat
• agentbridge_create_handoff
• agentbridge_list_handoffs
• agentbridge_claim_handoff
• agentbridge_submit_artifact
• agentbridge_get_artifact
• agentbridge_get_artifact_content
• agentbridge_request_review
• agentbridge_create_approval
• agentbridge_submit_review
• agentbridge_complete_handoff
• agentbridge_acquire_file_lock
• agentbridge_release_file_lock
• agentbridge_list_file_locks
• agentbridge_list_file_conflicts
• agentbridge_resolve_file_conflict
• agentbridge_list_audit_logs
• agentbridge_create_project_memory
• agentbridge_list_project_memory
• agentbridge_search_project_memory
• agentbridge_update_project_memory
• agentbridge_delete_project_memory
• agentbridge_start_work_session
• agentbridge_list_work_sessions
• agentbridge_checkpoint_progress
• agentbridge_resume_project

Resume workflow tools:

• agentbridge_start_work_session starts tracking a feature/task in progress.
• agentbridge_checkpoint_progress records where the agent is before stopping.
• agentbridge_resume_project generates the continuation packet and prompt for another agent.

Run

From this directory:

python -m agentbridge_mcp.server

When installed as a package:

agentbridge-mcp

One-Command Resume

Record the current stopping point before switching agents or hitting a usage limit:

PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.checkpoint_cli \
  --project-id <project_id> \
  --summary "Implemented backend slice and verified focused tests." \
  --current-step "Ready to hand off" \
  --next-step "Continue from the recorded checkpoint"

When installed as a package:

agentbridge-checkpoint \
  --project-id <project_id> \
  --summary "Implemented backend slice and verified focused tests." \
  --next-step "Continue from the recorded checkpoint"

The checkpoint command reads local git state by default: branch, latest commit, worktree path, and dirty files. Use --no-git to disable auto-detection.

Generate a resume packet for another agent:

PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.resume_cli \
  --project-id <project_id> \
  --target-agent antigravity

Save it locally:

PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.resume_cli \
  --project-id <project_id> \
  --target-agent antigravity \
  --output .agentbridge/resume-antigravity.md

When installed as a package:

agentbridge-resume --project-id <project_id> --target-agent antigravity

The command reads AGENTBRIDGE_API_URL and AGENTBRIDGE_AGENT_KEY from the environment, calls the resume packet API, prints the generated prompt, and optionally saves it. It also prints safety_status and should_continue so the next agent can pause when locks or conflicts are present. If expires_at has passed, it prints a stale packet warning and the agent should regenerate the packet before continuing. It never prints agent keys.

With --json, the command also adds a local is_expired boolean so scripts can block continuation without parsing timestamps themselves.

Test

The tool layer can be tested without a live backend:

PYTHONPATH=src pytest tests -q

Terminal Demo

Mock mode works without a backend:

PYTHONPATH=src python -m agentbridge_mcp.demo

Live mode uses AGENTBRIDGE_API_URL and AGENTBRIDGE_AGENT_KEY, then prompts for the Antigravity key, project ID, and agent IDs. Use the Codex key as AGENTBRIDGE_AGENT_KEY.

PYTHONPATH=src python -m agentbridge_mcp.demo --live

Live Backend Validation

Run these after the API is running on http://127.0.0.1:8000:

PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.live_artifact_validation
PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.live_coordination_validation
PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.live_resume_validation
PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.live_cli_resume_validation \
  --output /tmp/agentbridge-cli-resume.md
PYTHONPATH=src ../api/.venv/bin/python -m agentbridge_mcp.live_reverse_resume_validation

Required environment variables:

export AGENTBRIDGE_API_URL="http://127.0.0.1:8000"
export AGENTBRIDGE_AGENT_KEY="<codex_agent_key>"
export AGENTBRIDGE_PROJECT_ID="<project_id>"
export AGENTBRIDGE_CODEX_AGENT_ID="<codex_agent_id>"
export AGENTBRIDGE_ANTIGRAVITY_AGENT_ID="<antigravity_agent_id>"
export AGENTBRIDGE_ANTIGRAVITY_AGENT_KEY="<antigravity_agent_key>"

live_reverse_resume_validation uses AGENTBRIDGE_ANTIGRAVITY_AGENT_KEY to create/checkpoint a handoff targeting Codex, then uses AGENTBRIDGE_AGENT_KEY as Codex to generate the resume packet and verify the latest Antigravity checkpoint is preserved.

IDE Validation Checklist

Use the adapter configs in adapters/codex and adapters/antigravity.

1. Start the API:

   cd services/api
   .venv/bin/uvicorn main:app --port 8000
   

2. Confirm health:

   curl http://127.0.0.1:8000/api/v1/health
   

3. Configure Codex with the Codex agent key and Antigravity with the Antigravity agent key.

4. From Codex, call agentbridge_heartbeat.

5. From Codex, create a handoff assigned to Antigravity.

6. From Antigravity, list assigned handoffs and claim the new handoff.

7. From Antigravity, submit an artifact and request Codex review.

8. From Codex, fetch the artifact content, submit the review, and complete the handoff.

9. If any MCP tool fails in the IDE but works from terminal validation, record the exact tool name, payload, and API error before changing backend behavior.