Skip to main content
Glama

SynAgent MCP - Cross-Agent CLI Bridge

An intelligent cross-agent orchestration bridge connecting IDEs (VS Code, Cursor, Antigravity) with local coding agent CLIs (OpenAI Codex CLI, Claude Code, and Gemini CLI) via the Model Context Protocol (MCP).


⚡ Prerequisites & Agent Status

SynAgent bridges your IDE with your local CLI agents. You need at least one supported CLI installed and authenticated on your machine:

Provider

Status in v1.0

Model Families

Installation

Interactive Sign-In

OpenAI Codex

Active Backend

Sol, Luna, Astra

npm install -g @openai/codex

codex login

Claude Code

Active Backend

Sonnet 3.7, Opus

npm install -g @anthropic-ai/claude-code

claude auth login

Gemini CLI

Probed Backend

Flash, Pro

npm install -g @google/gemini-cli

gemini (follow prompts)

NOTE

Run thesynagent_doctor tool anytime to check your machine's environment, active versions, and authentication readiness.

IMPORTANT

Strict User Consent & Privacy Policy:

  • Zero Silent Downloads: SynAgent never downloads, installs, or executes packages in the background. If a CLI is missing, synagent_doctor provides the exact terminal command.

  • Read-Only Sandbox Guard: All diagnostic, review, analysis, and consultation tasks run in enforced read-only mode (--sandbox read-only on Codex, --permission-mode dontAsk --tools Read,Glob,Grep on Claude) to protect your repository from unintended edits.


Related MCP server: Context7 MCP Server

Architecture: Maker–Checker Pattern

SynAgent establishes an automated Maker–Checker (Builder–Auditor) pair programming workflow:

  • Primary IDE Assistant (VS Code, Cursor, Antigravity): Interactive development, file editing, test execution, and Git management.

  • Local CLI Reasoning Engines: Deep independent verification, root-cause debugging, non-interactive audit, and second opinions running safely in read-only sandbox mode.

[ VS Code / Cursor / Antigravity ]
               │
        (MCP over stdio)
               ▼
        synagent server (v0.9.0-dev)
               │
   ┌───────────┼───────────┐
   ▼           ▼           ▼
Codex CLI   Claude Code  Gemini CLI
(Active)    (Active)     (Probed)

Tool Reference

Universal Multi-Agent Tools

Primary Tool

Legacy Alias

Description

Key Parameters

synagent_doctor

omniagent_doctor

Comprehensive multi-agent diagnostic audit. Checks presence, versions, paths, and auth status of all 3 CLIs.

None

synagent_review

omniagent_review

Automated code review with full Git scope support across uncommitted, staged, commit, or branch diffs.

scope, instructions, backend: "auto"|"codex"|"claude"

synagent_consult

omniagent_consult

Second opinion and architectural evaluation for proposed refactoring plans or designs.

proposal, specific_questions, backend: "auto"|"codex"|"claude"

synagent_analyze

omniagent_analyze

In-depth structural, architectural, and dependency analysis in read-only mode.

task, file_paths, backend: "auto"|"codex"|"claude"

synagent_quota_status

omniagent_quota_status

Current rolling limit headroom and usage telemetry across backends.

refresh

synagent_set_default

omniagent_set_default

Persist default CLI backend in ~/.synagent/config.json.

backend

synagent_close_session

omniagent_close_session

Cleanly terminate an active multi-turn session.

session_handle

synagent_report_bug

omniagent_report_bug

Privacy-sanitized bug report and pre-filled GitHub issue URL.

error_message, context

100% Backward-Compatible Codex Tools

All existing codex_* tools are preserved with identical schemas and semantics:

  • codex_status — Retrieves configuration, daemon status, and active model policies.

  • codex_review_code — Automated code review pinned to Codex CLI.

  • codex_consult — Architectural second opinion pinned to Codex CLI.

  • codex_analyze — Codebase and structural analysis pinned to Codex CLI.

  • codex_debug_error — Root-cause debugging and fix recommendations for error traces.

  • codex_implement — Synthesis of complex algorithms and class scaffolds (read-only output).


Review Scope Architecture (synagent_review)

SynAgent supports granular Git scope targeting:

Scope Format

Example

Description

Working Changes (Default)

"uncommitted", ""

All unstaged, staged, and untracked changes across the working tree.

Staged Index Only

"staged", "cached"

Only changes added to the Git staging index (git diff --cached).

Single Commit

"c502bf5", "commit:c502bf5"

Diffs introduced by a specific commit SHA (git show <sha>).

Relative Revision

"HEAD~1", "HEAD^"

Diffs introduced by a relative ancestor revision (git show HEAD~1).

Branch / PR Comparison

"main", "origin/main"

Comparison of current branch against base branch (git diff <base>...HEAD).

Revision Range

"main...feature", "v1.0..v2.0"

Diffs across any valid two-dot or three-dot revision range.

All scope arguments are strictly sanitized to prevent option injection, and prompts are piped via standard input to eliminate command-line character limits on Windows.


Safety & Governance Guardrails

To prevent accidental consumption of high-tier resources, top-tier models (astra in Codex, claude-3-opus in Claude) are strictly guarded:

  1. Interactive Prompt: The caller must prompt the user before initiating requests with this tier.

  2. Server-Side Enforcement: The server rejects calls requesting top-tier models unless user_confirmed: true is explicitly passed.


Installation & Configuration

1. Install via npm

npm install -g synagent
# or run directly with npx:
npx synagent

2. Configure in your IDE

VS Code (User/mcp.json)

{
  "servers": {
    "io.github.oki-dev/synagent": {
      "type": "stdio",
      "command": "synagent"
    }
  }
}

Antigravity & Cursor (mcp_config.json)

{
  "mcpServers": {
    "synagent": {
      "command": "synagent"
    }
  }
}

Automated Test Suite

SynAgent includes a test suite using the native Node.js test runner:

npm test

Author & License

Available Tools

6 tools
codex_analyzeB

Perform deep architectural, dependency, and structural code analysis in read-only sandbox mode using OpenAI Codex.

Inputs: task (required), model, file_paths, user_confirmed, +2 more.

codex_consultB

Consult OpenAI Codex for a second opinion on an architecture plan, refactoring strategy, or technical trade-offs.

Inputs: proposal (required), model, user_confirmed, workspace_path, +2 more.

codex_debug_errorC

Consult OpenAI Codex to diagnose errors, exceptions, stack traces, or unexpected test/build failures and suggest solutions.

Inputs: error_message (required), model, context, file_paths, +3 more.

codex_implementA

Request OpenAI Codex to synthesize complex code, algorithms, structural refactorings, or boilerplate in read-only sandbox mode.

Inputs: specification (required), model, context_files, user_confirmed, +2 more.

codex_review_codeA

Run an automated code review on uncommitted repository changes or a specific git diff using OpenAI Codex in read-only mode.

Inputs: model, scope, instructions, user_confirmed, +2 more.

codex_statusA

Get the active OpenAI Codex CLI configuration, active model, reasoning effort, and governance policies (e.g. Astra approval rules).

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation4/5

    The tools target distinct Codex usage modes: status, analysis, debugging, review, implementation, and consultation. However, codex_analyze, codex_consult, and codex_review_code have adjacent boundaries that could cause occasional misselection.

    Naming Consistency4/5

    All tools use a consistent codex_ prefix and snake_case, which makes the set predictable. There is minor inconsistency between verb-only names (codex_analyze, codex_implement, codex_consult), verb_noun names (codex_debug_error, codex_review_code), and a noun name (codex_status).

    Tool Count5/5

    Six tools is well-scoped for a Codex CLI wrapper, and each tool represents a meaningful, non-redundant operation. The count is neither thin nor bloated.

    Completeness4/5

    The surface covers common Codex interactions including status, analysis, debugging, review, implementation, and consultation. Minor gaps exist around applying changes, continuing sessions, or explicitly generating/running tests, but agents can work around these limitations.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Bridges the Model Context Protocol with Language Server Protocol to provide AI agents with persistent access to code intelligence features including navigation, diagnostics, refactoring, and completion across 7+ programming languages.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Remote MCP coding bridge that gives ChatGPT/Codex secure local workspace access, including file retrieval, semantic code intelligence, Git, diagnostics, and guarded shell execution.
      55 npm
      MIT