agentic-mcp

Prove and compare the AI CLIs you already installed, from one command surface or one MCP setup.

agentic-mcp helps you prove an installed provider CLI can do real work, compare multiple installed providers on the same prompt, and reuse one workflow across terminal and MCP clients.

Who this is for

• Terminal-first developers who already have at least one provider CLI installed
• Developers who want to compare two installed providers on the same prompt
• MCP client users who want one reusable setup path for Claude Code, Cursor, or Windsurf
• Tool and agent builders who want a consistent ask, ping, and comparison surface across installed CLIs

Who should skip it

• Users who only need one provider and are happy with that provider's native CLI
• Users looking for hosted routing, hosted billing, or a cloud model marketplace
• Users who do not yet have any provider CLI installed or authenticated

Why this exists

• Installed AI CLIs expose different proof paths, flags, and workflows
• Comparing providers by hand means rerunning the same prompt and collecting outputs yourself
• MCP client setup becomes repetitive when each tool wants its own integration entry
• agentic-mcp keeps proof, comparison, and reusable setup in one workflow

Choose your path in 30 seconds

• I already installed one provider and I want proof it can answer real work from the terminal. Start here: Get your first real answer from the terminal

• I already installed two providers and I want to compare which one gives the better answer. Start here: Compare two providers on the same prompt

• I already use Claude Code and I want the same proof-and-compare workflow there without wiring each provider separately. Start here: Reuse one Claude Code setup across my installed providers

MCP is how editor and agent clients reach the same workflow. It is the delivery mechanism, not the reason to use the project.

Concrete scenarios

• "I installed Claude and want to know whether it is actually authenticated before I wire it into anything else."
• "I installed Claude and Codex and want to compare their refactor suggestions on the same prompt."
• "I already work in Claude Code and want one reusable setup instead of separate per-provider MCP entries."

When to use something else

• Use a provider's native CLI when one provider is enough and you do not need comparison or MCP reuse
• Use llm when you want a broad plugin-centric CLI for local and remote models
• Use OpenRouter when you want hosted multi-model routing behind one API
• Use mcpc when your main goal is configure-once MCP portability and you do not need installed-CLI proof or side-by-side comparison
• Use agentic-mcp when you already work through installed provider CLIs and want proof, comparison, and one reusable workflow

How it works

1. You install and authenticate one or more provider CLIs locally.
2. agentic-mcp helps you prove one works for a real task and compare several on the same prompt.
3. If you want editor or agent integration, you reuse that same workflow through an MCP client.

Before you start

You need:

• Node.js 22 or newer
• At least one supported provider CLI installed locally and already authenticated
• An MCP client only if you want editor or agent integration; direct CLI usage works without one

Supported provider binaries today:

• Core enabled providers: claude, codex, copilot, gemini, opencode
• Additional enabled providers: aider, goose, amp, cline, agent (Cursor Agent CLI), droid
• Disabled templates shipped for later verification: q (Amazon Q), plandex, openhands, qwen, tabnine

list_providers is the source of truth for what is enabled, what is disabled, which support level each provider is in, and which prerequisites a template still needs. If the underlying binary is missing or not logged in, setup may still succeed while provider calls fail.

Quickstart

1. Run minimal onboarding

npx agentic-mcp init

init is a safe onboarding alias for setup --minimal. It installs the bundled using-agentic-mcp skill, detects provider binaries, and tells you what is still unproven.

What this step proves:

• agentic-mcp is installed and can run locally
• the bundled skill is available for agent workflows
• which provider binaries are detected on this machine

What this step does not prove:

• MCP client config is written
• provider authentication works
• a real prompt can complete through a provider

2. Discover what is detected

npx agentic-mcp list_providers

What this step proves:

• which providers are binary detected, binary missing, or disabled
• which support level each configured provider reports
• which prerequisites a disabled template still expects
• which provider should be your first real-answer candidate

What this step does not prove:

• provider authentication works
• a real prompt can complete through that provider

3. Get your first real answer

npx agentic-mcp prove

Use npx agentic-mcp prove codex if you want to force a specific detected provider.

What this step proves:

• agentic-mcp can pick a detected provider and route a real prompt through it
• your installed provider is usable for real work through this project

Milestone: You have now successfully routed a real provider through agentic-mcp.

4. Compare providers when two are usable

npx agentic-mcp ask_all "Reply with one sentence on why your answer is useful here." --providers claude,codex --report ./reports/first-comparison.json

Use this only when you want side-by-side comparison on the same prompt. Add --report <path> when you want to keep the structured comparison as a reusable JSON artifact.

What this step proves:

• you can compare providers through one interface instead of hand-running the same prompt multiple times
• ask_all is the product's comparison workflow, not just an advanced extra
• the comparison can be saved and reused outside the terminal

Milestone: You have now completed your first side-by-side provider comparison through agentic-mcp.

5. Optional: run a limited ping check

npx agentic-mcp ping_claude

Replace claude with the provider you actually installed.

What this step proves:

• the selected provider binary was detected
• the version check works if that provider exposes one

What this step does not prove:

• provider authentication works
• a real provider answer can complete

6. Add MCP client setup when you want editor or agent integration

If you want MCP tools inside Claude Code, Cursor, or Windsurf, write the client config entry now:

npx agentic-mcp setup --client claude-code --yes
npx agentic-mcp setup --client cursor --yes
npx agentic-mcp setup --client windsurf --yes

For another MCP client, generate a generic JSON entry and choose the target file yourself:

npx agentic-mcp setup --client generic --path /path/to/mcp.json --yes

If you want to preview changes before writing, add --dry-run. If you only care about terminal usage, you can stop after the proof steps above.

What this step proves:

• agentic-mcp can write or preview the MCP client entry
• the setup output tells you what was configured, what was detected, and what remains unproven

What this step does not prove:

• provider authentication works
• a real provider response can complete through agentic-mcp

If you are using MCP mode, restart your client after setup and confirm that tools such as list_providers, ping_<provider>, ask_<provider>, and review_<provider> where supported appear.

Supported MCP clients

| Client | Setup command | Default config path | | ------------ | ----------------------------------------------------------------------- | -------------------------------------- | | Claude Code | npx agentic-mcp setup --client claude-code --yes | ~/.claude/claude_desktop_config.json | | Cursor | npx agentic-mcp setup --client cursor --yes | ~/.cursor/mcp.json | | Windsurf | npx agentic-mcp setup --client windsurf --yes | ~/.codeium/windsurf/mcp_config.json | | Generic JSON | npx agentic-mcp setup --client generic --path /path/to/mcp.json --yes | user-supplied |

Setup uses merge mode by default, preserves existing MCP servers, creates backups when appropriate, and verifies writes after updating the file.

For Claude tooling, the setup target name is claude-code, but the config file it updates is ~/.claude/claude_desktop_config.json. That filename comes from the client-side config convention, not from this package.

Common workflows

Use it as a direct CLI

You do not need an MCP client to use agentic-mcp.

npx agentic-mcp prove
npx agentic-mcp ask_claude "What changed in TypeScript 5.9?"
npx agentic-mcp ask_codex "Suggest a refactor for this function"
npx agentic-mcp sessions_claude

When run without a subcommand, agentic-mcp starts as an MCP stdio server.

Review repository changes with a provider

Today this is primarily useful with review_codex, because Codex is the first shipped provider with a review command.

npx agentic-mcp review_codex --scope uncommitted --working-dir .

Review flags:

| Flag | Meaning | When to use it | | ------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------- | | --scope uncommitted | Review staged, unstaged, and untracked changes | Fast pass on your current working tree | | --scope commit --commit <sha> | Review one commit | Focus on a single change set | | --scope range --base <ref> | Review everything relative to a base branch or ref | Review a feature branch against main | | --working-dir <path> | Run the review in a specific repository root | Required when your current shell directory is not the repo you want reviewed | | --model <name> | Pass a provider-specific model hint | Override the provider default when needed | | --stream-live | Show live review progress in the terminal | Useful for longer reviews so the command does not look idle |

Examples:

npx agentic-mcp review_codex --scope uncommitted --working-dir .
npx agentic-mcp review_codex --scope commit --commit HEAD~1 --working-dir .
npx agentic-mcp review_codex --scope range --base origin/main --working-dir . --model gpt-5

The review command is routed through the same MCP tool surface as ask_<provider>, so editor clients can expose review_<provider> when that provider declares a review command.

Compare providers on the same prompt

npx agentic-mcp ask_all "Summarize this API design" --providers claude,codex,gemini
npx agentic-mcp ask_all "Compare providers" --providers gemini codex
npx agentic-mcp ask_all "Use one shared model" --providers claude,gemini --model claude-sonnet-4
npx agentic-mcp ask_all "Compare bugfixes" --providers claude,codex --report ./reports/bugfixes.json

Use this when you want side-by-side answers without hand-running the same prompt several times. Add --report <path> when you want a saved JSON artifact of the comparison.

ask_all flag semantics

| Flag | Meaning | Accepted forms | Notes | | ------------- | --------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------ | | --provider | Provider selector alias | --provider gemini, --provider gemini codex | Normalized to --providers | | --providers | Explicit provider selection | --providers gemini,codex, --providers gemini codex | Comma-separated and space-separated values are both accepted | | --model | Shared model hint for every selected provider | --model claude-sonnet-4 | Pass exactly one shared model value | | --models | Shared model hint alias | --models claude-sonnet-4 | Normalized to --model before parsing |

ask_all flag combinations

• --providers or --provider decides which providers run.
• --model or --models decides which shared model hint is passed to those selected providers.
• --model takes exactly one shared model value. Use --providers for provider selection.
• If you combine --providers with --model, provider selection comes from --providers and the shared model comes from --model. Example: --providers claude,gemini --model claude-sonnet-4.
• If a selected provider rejects the shared model as unavailable or unsupported, ask_all returns that provider error directly instead of falling back to a different model.
• Unknown ask_all flags still fail fast with a validation error.

Check what is detected on this machine

npx agentic-mcp list_providers
npx agentic-mcp ping_claude
npx agentic-mcp help_claude
npx agentic-mcp provider_metrics

provider_metrics is the after-action view: it tells you which providers you actually used, how often they succeeded, and how long they took.

Built-in provider support

These provider definitions ship with the project. Whether they are actually usable on your machine still depends on the underlying CLI binary being installed and authenticated.

| Provider | Binary | Support level | Enabled by default | Notes | | --------- | ----------- | ------------- | ------------------ | ------------------------------------ | | Claude | claude | stable | Yes | ask, sessions | | Codex | codex | stable | Yes | ask, review, sessions | | Copilot | copilot | stable | Yes | ask, sessions | | Gemini | gemini | stable | Yes | ask | | OpenCode | opencode | stable | Yes | ask, sessions, model listing | | Aider | aider | community | Yes | ask | | Goose | goose | beta | Yes | ask, sessions | | Amp | amp | beta | Yes | ask | | Cline | cline | beta | Yes | ask | | Cursor | agent | beta | Yes | ask | | Droid | droid | beta | Yes | ask | | Amazon Q | q | experimental | No | disabled template with prerequisites | | Plandex | plandex | community | No | disabled template with prerequisites | | OpenHands | openhands | experimental | No | disabled template with prerequisites | | Qwen Code | qwen | experimental | No | disabled template with prerequisites | | Tabnine | tabnine | experimental | No | disabled template with prerequisites |

Provider definitions live in src/config/providers.json.

Useful setup flags

agentic-mcp setup supports a few flags that matter often:

• --minimal - install the skill and print suggested next steps without writing client config
• --dry-run - preview the planned change without writing files
• --yes - allow non-interactive writes
• --mode merge|overwrite - choose how an existing config file is updated
• --path <file> - target a specific config file
• --backup if-exists|always|never - control backup behavior
• --output json - machine-readable setup output

Command overview

npx agentic-mcp <command> [options]

Core commands:

| Command | What it does | | ------------------------- | ---------------------------------------------------------------------------------------- | | ask_<provider> <prompt> | Query one provider | | review_<provider> | Run repository review where that provider declares a review command | | ask_all <prompt> | Query several providers in parallel | | ping_<provider> | Check limited provider proof | | help_<provider> | Show the provider CLI help output | | sessions_<provider> | List known sessions for that provider | | list_providers | Show configured providers with detected status, support levels, and prerequisites | | provider_metrics | Show which providers you actually used, how often they succeeded, and how long they took | | prove [provider] | Run one canned real-answer proof against a detected provider | | setup | Configure an MCP client |

Run npx agentic-mcp --help for the full CLI reference.

AI agent setup guides

If you want another AI agent to discover and use this project reliably:

• Read the agent workflow guide: MCP-SKILLS-DISCOVERABILITY.md
• Use the bundled skill: skills/using-agentic-mcp/SKILL.md
• Start from a goal-based path: docs/getting-started

That material is useful once the basic setup above works. It is not required for a normal first run.

Development

pnpm install
pnpm run dev
pnpm run build
pnpm run test
pnpm run typecheck
pnpm run lint

If you want to inspect the MCP server manually:

pnpm run inspect

Contributing

See CONTRIBUTING.md.

License

MIT