MCP Orchestration

MCP Orchestration Skill (canonical)

Version: 2.0.0 Date: 2026-05-14 Scope: Claude Code, Claude Desktop, OpenClaw, Gemini MCP Tool, ai-cli-mcp, OpenRouter, local ollama, custom MCP servers Status: canonical. Supersedes the two root MCP_ORCHESTRATION_SKILL*.md files. Sources merged and drift removed.

Canonical location: orama-system/bin/orama-system/mcp-orchestration/SKILL.md All other copies (root markdown, user-level ~/.claude/skills/mcp-orchestration/SKILL.md) should be redirect stubs pointing here.

Executive Rule

Use the right tool for the right layer. Use the cheapest agent that can succeed.

Two routing rules below override the legacy "Gemini = default reader" pattern. See §2.

1. MCP Fundamentals

MCP lets Claude and other agents call external tools through a standard tool protocol.

Common transport

Most local MCP tools here use stdio — the MCP client starts the tool as a local subprocess and talks to it over stdin/stdout.

Common config shapes

Claude Desktop and many MCP clients:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name"]
    }
  }
}

OpenClaw outbound MCP registry:

{
  "mcp": {
    "servers": {
      "server-name": {
        "command": "npx",
        "args": ["-y", "package-name"]
      }
    }
  }
}

Claude Code verification

Inside Claude Code: /mcp CLI: claude mcp list

2. Routing strategy (READ FIRST)

Rule 1 — Default routing: OpenRouter free-model stack

When the caller does NOT specify an agent, route to OpenRouter free models in fallback order:

1. openrouter/nvidia/nemotron-3-super-120b-a12b:free   (1M ctx, agent-strong)
2. openrouter/minimax/minimax-m2.5:free                (205K, 80.2% SWE-Bench)
3. openrouter/deepseek/deepseek-v4-flash:free          (1M, fast triage)
4. openrouter/openai/gpt-oss-120b:free                 (131K, tool-use)
5. openrouter/z-ai/glm-4.5-air:free                    (131K, agentic backup)
6. openrouter/inclusionai/ling-2.6-flash:free          (262K, lightweight)
7. openrouter/openrouter/free                          (auto-router, last resort)

For local-machine workloads where no network is needed, prefer ollama qwen3.5 on Mac (localhost:11434) FIRST. Then fall through to OpenRouter.

See docs/OPENROUTER_FREE_MODELS.md for the full policy and scripts/apply-openrouter-free-defaults.sh for applying it to openclaw.json configs.

Rule 2 — Gemini-Analyzer use-case routing (when specified)

Gemini is NOT the default reader. Gemini has unique strengths but also access constraints (GitHub auth issues, rate limits). Reserve it for explicitly-specified "Gemini-Analyzer use-cases":

For ANY OTHER reading task (single file, narrow audit, dependency scan), route to OpenRouter Nemotron 3 Super (1M ctx, free) instead.

Call signature pattern:

# Default reader call (uses OpenRouter):
"Read @path/to/file and report X"

# Gemini-Analyzer call (explicit):
"GEMINI-ANALYZER: visual-diff between @screenshot.png and live dev server"

Rule 3 — Claude Sonnet 4.6 medium for judgment + prompt caching

Reserve Claude Sonnet 4.6 (this session's main agent) for:

• Final judgment, taste calls, conflict resolution
• Reviewing worker outputs and detecting drift
• Content insertion decisions (CIDF gate)
• Writing commit messages, summaries, designs

Prompt caching policy (Goal 2 from RC-1 plan):

When using Claude Sonnet 4.6 via the Anthropic SDK:

• model: claude-sonnet-4-6
• thinking.effort: medium
• Set cache_control on stable system prompts, tool definitions, and context prefixes
• Simplest option — automatic placement: pass a single cache_control field at the top level of the messages.create() request and the SDK auto-places the breakpoint on the last cacheable block. Reach for explicit per-block cache_control (shown below) only when you need fine-grained control over multiple breakpoints (max 4).
• Sonnet 4.6 minimum cacheable prompt: 1,024 tokens (anything smaller is not cached)
• TTL: 5 minutes default (90 minutes with ttl: "extended")
• NEVER cache changing suffixes — timestamps, per-run user payloads, request IDs, response IDs

Example (Python SDK):

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    thinking={"type": "enabled", "budget_tokens": 8000},
    system=[
        {
            "type": "text",
            "text": LARGE_STABLE_SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"},  # ← cache this
        }
    ],
    messages=[
        {"role": "user", "content": ephemeral_user_input}  # ← do NOT cache
    ],
)

Source: https://platform.claude.com/docs/en/build-with-claude/prompt-caching

Rule 4 — Use ai-cli-mcp as the parallel worker pool

Use ai-cli-mcp when:

• Tasks are independent (different files, different concerns)
• Multiple models should inspect the same repo
• You need background agents with PID tracking
• You want session reuse across subtasks

Do not let worker agents commit or deploy without explicit user confirmation.

Rule 5 — OpenClaw as the runtime router

OpenClaw routes tools into agent workflows, holds gateway/auth, registers outbound MCP servers, and keeps security/policy around agent execution.

3. Install Baseline

Use Node.js 20+ when using both Gemini MCP Tool and ai-cli-mcp.

node -v
npm -v

Install Claude Code

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

For ai-cli-mcp Claude workers, run once manually:

claude --dangerously-skip-permissions

This accepts prompts so background Claude subprocesses do not hang.

Verify Claude auth (REQUIRED before dispatching Claude workers)

Before routing work to Claude, verify auth through the exact binary the orchestrator will use:

which claude
claude --version
claude auth status --text
claude -p --permission-mode dontAsk --max-budget-usd 0.25 "Reply with exactly: claude-ready"

If claude -p reports Not logged in after a login attempt, assume the auth flow may have been sandbox-blocked until proven otherwise. Claude's OAuth flow needs a local callback server and host credential persistence. Run login outside the sandbox or with explicit escalation:

claude auth login --claudeai
claude auth status --text
claude -p --permission-mode dontAsk --max-budget-usd 0.25 "Reply with exactly: claude-ready"

If login prints success but auth status remains false, inspect a debug log:

claude --debug --debug-file /tmp/claude-auth-debug.log auth login --claudeai
sed -n '1,120p' /tmp/claude-auth-debug.log

Failed to start OAuth callback server is a sandbox/auth-environment failure, not a normal stale session. Escalate the auth command instead of looping.

If the machine has both native and npm-global Claude installs, compare which claude, claude --version, and known full paths. Use one exact binary for login, status, and -p probes.

Install Gemini CLI

npm install -g @google/gemini-cli
gemini auth login
gemini --version

Non-interactive subagent dispatch (verified 2026-06-14): gemini -p "/goal <task>" delegates to agent personas (codebase_investigator, generalist, cli_help). The Antigravity CLI (agy -p "/goal <task>", multi-model: Gemini 3.x / Claude Sonnet+Opus 4.6 / GPT-OSS 120B; list with agy models) is the parallel-orchestrator sibling. Full command guide: agy-gemini.md at the workspace root. Dispatch lanes, model picks, and bounding (gtimeout, never sleep chains) are in code-review/references/orchestration-dispatch.md.

Install Codex CLI (optional, Codex worker support)

npm install -g @openai/codex
codex login

Install ai-cli-mcp

npm install -g ai-cli-mcp
ai-cli doctor
ai-cli models

Install ollama (for local-priority routing per Rule 1)

curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen3.5:9b-nvfp4   # Mac default model
ollama serve                    # listens on localhost:11434

4. gemini-mcp-tool

Repository: jamubc/gemini-mcp-tool

Purpose

Bridges Gemini CLI into Claude Code or other MCP clients. Used only for Gemini-Analyzer use-cases per §2 Rule 2.

Claude Code setup

claude mcp add gemini-cli -- npx -y gemini-mcp-tool

Verify: /mcp → expect gemini-cli active

Claude Desktop setup

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gemini-cli": {
      "command": "npx",
      "args": ["-y", "gemini-mcp-tool"]
    }
  }
}

Restart Claude Desktop.

Reader Protocol (Gemini-Analyzer mode)

1. Mark the call as Gemini-Analyzer (explicit user intent)
2. Ask Gemini a NARROW reading question with structured output
3. Ask Claude to verify the evidence
4. Let Claude decide

Good:

Ask Gemini to identify stale architecture claims in @README.md and @docs/. Return file, claim, contradiction, confidence.

Bad:

Ask Gemini to fix the repo.

Model selection

Windows / Parallels note

Use official gemini-mcp-tool first. A package like gemini-mcp-tool-windows-fixed is a local workaround only.

5. ai-cli-mcp

Repository: mkXultra/ai-cli-mcp

Purpose

Runs AI CLI tools as background worker processes with PID tracking, result retrieval, waiting, killing, cleanup.

Critical first run

Run once:

claude --dangerously-skip-permissions
codex login
gemini auth login

Claude Code setup

claude mcp add ai-cli '{"name":"ai-cli","command":"npx","args":["-y","ai-cli-mcp@latest"]}'

Generic MCP config

{
  "mcpServers": {
    "ai-cli-mcp": {
      "command": "npx",
      "args": ["-y", "ai-cli-mcp@latest"],
      "env": {
        "MCP_CLAUDE_DEBUG": "false"
      }
    }
  }
}

Core tools

Parallel dispatch pattern

Use ai-cli-mcp to run three workers in parallel:

1. model=sonnet
   workFolder=/absolute/path/project
   prompt="Review src/backend for risky refactors. Return findings only."

2. model=gpt-5.2-codex
   workFolder=/absolute/path/project
   prompt="Write test suggestions for src/frontend. Do not edit files."

3. model=openrouter/nvidia/nemotron-3-super-120b-a12b:free
   workFolder=/absolute/path/project
   prompt="Read the repo and find stale docs. Return file list."

Then wait for all PIDs.
Merge outputs.
Do not modify files until I approve.

Worker safety

• Use absolute workFolder
• Avoid destructive actions
• Do not allow background agents to commit
• Require explicit user confirmation for writes, deletes, deploys, account changes
• Kill runaway PIDs
• Archive useful results into learnings.md only after review

6. OpenClaw Integration

Two roles

Add ai-cli-mcp + Gemini to OpenClaw outbound registry

openclaw mcp set ai-cli-mcp '{"command":"npx","args":["-y","ai-cli-mcp@latest"],"env":{"MCP_CLAUDE_DEBUG":"false"}}'
openclaw mcp set gemini-cli '{"command":"npx","args":["-y","gemini-mcp-tool"]}'
openclaw mcp list

OpenClaw model policy (uses OpenRouter free-model stack per Rule 1)

The default OpenClaw model policy points at OpenRouter free fallbacks. Apply with:

scripts/apply-openrouter-free-defaults.sh --repo-only
scripts/apply-openrouter-free-defaults.sh --apply-live   # patches ~/.openclaw/openclaw.json

Full config shape lives in deployments/macbook-pro-head/openclaw/openclaw.model-policy.jsonc. See docs/OPENROUTER_FREE_MODELS.md.

OpenClaw config shape (combined)

{
  "env": {
    "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}"
  },
  "mcp": {
    "servers": {
      "ai-cli-mcp": {
        "command": "npx",
        "args": ["-y", "ai-cli-mcp@latest"],
        "env": { "MCP_CLAUDE_DEBUG": "false" }
      },
      "gemini-cli": {
        "command": "npx",
        "args": ["-y", "gemini-mcp-tool"]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/nvidia/nemotron-3-super-120b-a12b:free",
        "fallbacks": ["openrouter/minimax/minimax-m2.5:free", "openrouter/openrouter/free"]
      }
    }
  }
}

Dispatch rule (embed in OpenClaw instructions)

Use OpenRouter free-model stack as the default agent.
Use Gemini only for Gemini-Analyzer use-cases (visual diff, whole-repo, multi-file audits).
Use ai-cli-mcp for isolated parallel work.
Never write, delete, deploy, or commit unless the user explicitly confirms YES.
After workers finish, summarize by PID and cite each worker result.

7. Build a New Claude Skill

Locations

• Personal: ~/.claude/skills/<skill-name>/SKILL.md
• Project: .claude/skills/<skill-name>/SKILL.md
• Repo-canonical (orama-system pattern): bin/orama-system/<skill-name>/SKILL.md

Minimal template

---
name: build-optimizer
description: Diagnoses and fixes build failures. Use when the user mentions ENOTEMPTY, npm install failures, package manager errors, macOS file locks, or failing builds.
---

# Build Optimizer

## Instructions

When fixing build failures:

1. Identify the package manager.
2. Capture the exact error.
3. Check for file locks.
4. Remove only generated folders.
5. Reinstall dependencies.
6. Run the smallest proof test.

## Safety

Do not delete source files.
Ask before deleting unknown folders.

Skill discovery rule

The description is the trigger surface — be specific.

Good: description: Diagnoses MCP setup issues for Claude Code, Gemini MCP Tool, ai-cli-mcp, and OpenClaw. Use when MCP servers fail, tools do not appear in /mcp, JSON parse errors occur, or background agents hang.

Bad: description: Helps with MCP.

8. Custom MCP Server Skill

Use only when existing tools do not provide the needed action.

Scaffold

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
mkdir -p src

Minimal TypeScript server

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "my-skill", version: "1.0.0" });

server.registerTool(
  "my_tool",
  {
    description: "Runs one safe custom action.",
    inputSchema: {
      action: z.string().describe("Action to perform"),
      target: z.string().optional().describe("Target resource"),
    },
  },
  async ({ action, target }) => ({
    content: [{ type: "text", text: `Executed ${action} on ${target ?? "default"}` }],
  }),
);

const transport = new StdioServerTransport();
await server.connect(transport);

Register

npx tsc
claude mcp add my-skill -- node dist/index.js

Security baseline

• Use allowlists
• Keep tools narrow
• Avoid broad filesystem access
• Do not pass secrets in prompts
• Use environment variables for credentials
• Require confirmation before destructive actions

9. Tool Search

Use tool search when many MCP servers or tools are configured:

ENABLE_TOOL_SEARCH=auto claude
ENABLE_TOOL_SEARCH=auto:5 claude

10. Troubleshooting

Windows UTF-8 fix

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$env:PYTHONIOENCODING = "utf-8"

11. LESSONS.md Pattern

Create learnings.md next to this SKILL.md. Append:

## YYYY-MM-DD: Short title

Problem:
Cause:
Fix:
Verification:
Promote to skill:
- no

Promotion rule:

12. Verification Checklist

node -v
npm -v
claude doctor
claude mcp list
gemini --version
ai-cli doctor
ai-cli models
ollama list
openclaw mcp list

Inside Claude Code: /mcp

Pass criteria:

• gemini-cli appears (if installed) — used for Gemini-Analyzer use-cases only
• ai-cli-mcp appears and is active
• ollama qwen3.5:9b-nvfp4 listed (Mac default)
• Claude CLI first-run prompt has been accepted
• ai-cli doctor detects installed CLIs
• OpenClaw lists outbound MCP servers
• OPENROUTER_API_KEY is set in env
• No secrets appear in logs

13. Agent Instruction Block

Use this in CLAUDE.md, OpenClaw instructions, or project agent docs:

# MCP Orchestration Policy

1. Default to OpenRouter free-model stack (Nemotron → MiniMax → DeepSeek → …) for generic worker calls.
2. Use ollama (local Mac) FIRST when no network/API is required (lint, format, bash scripts).
3. Use Gemini ONLY for Gemini-Analyzer use-cases: visual diff, whole-repo architecture, multi-file stale-doc detection, large-diff code review.
4. Use Claude Sonnet 4.6 medium + prompt caching for judgment, final synthesis, taste calls, content insertion.
5. Use ai-cli-mcp only for isolated parallel work with PID tracking.
6. Use absolute workFolder paths.
7. Never let worker agents commit, deploy, delete, or change account settings without explicit confirmation.
8. Verify every MCP server with `/mcp` or matching CLI status commands.
9. Keep MCP configs minimal.
10. Prefer allowlisted tools over broad permission bypass.
11. Record repeated fixes into learnings.md.
12. Promote repeated fixes into SKILL.md only after recurrence.

14. Decision Table

Final Rule

MCP is a tool layer. Do not turn every workflow into an MCP problem.

For one-time tasks, act directly. For repeated tasks, create a skill. For external capabilities, add an MCP server. For parallel work, use ai-cli-mcp. For Gemini-Analyzer use-cases (visual, large-context), use Gemini. For everything else, use OpenRouter free models or local ollama. For judgment, use Claude Sonnet 4.6 medium with prompt caching.

Applied pattern — multi-channel steelman: for a small but high-stakes change, fan the design out to a heterogeneous model panel (verify reachability first) for adversarial review. Recipe: docs/reference/multi-channel-steelman.md.

Appendix: Legacy file disposition

The following files are superseded by THIS canonical SKILL.md:

Update all references to point at orama-system/bin/orama-system/mcp-orchestration/SKILL.md.

D14 Mirror Enforcement

Before dispatching a worker, verify the backend does not route a windows_only spec to lmstudio-mac. resolve_backend_for_spec in orchestrator/backend_resolver.py raises PolicyUnavailable on this. NEVER catch and silently fall back — fail closed.

Source: diazMelgarejo/orama-system — distributed by TomeVault.