mcp-orchestration

name	mcp-orchestration
description	Use when setting up Claude Code MCP tools, adding Claude Skills, using Gemini as a large-context reader, dispatching parallel AI CLI agents, connecting MCP tools to OpenClaw, or routing tasks to local/OpenRouter/Codex/Gemini agents. Trigger when the user mentions Gemini MCP, ai-cli-mcp, OpenClaw MCP, SKILL.md, Claude Skills, background agents, /mcp, MCP JSON, prompt caching, OpenRouter routing, agent dispatch, or tool setup failures.
version	2.0.0
canonical_path	orama-system/bin/orama-system/mcp-orchestration/SKILL.md
supersedes	["OpenClaw/MCP_ORCHESTRATION_SKILL.md","OpenClaw/MCP_ORCHESTRATION_SKILL_v2.md","~/.claude/skills/mcp-orchestration/SKILL.md"]
last_updated	"2026-05-14T00:00:00.000Z"

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.

Layer	Tool	Job
Main reasoning + judgment	Claude Sonnet 4.6 medium + prompt caching	Decide, edit, review, synthesize, content insertion
Default coding/text agent	OpenRouter free-model stack (Nemotron → MiniMax → DeepSeek → …)	Generic worker, long-context, coding, structured output
Large-context reading, when explicitly requested	gemini-mcp-tool	Gemini-Analyzer use-cases only, architecture mapping, visual diff, screenshot comparison, multi-file audit
Parallel workers	ai-cli-mcp	Run background CLI agents (Codex, Gemini, ollama) with PID tracking
Local-only workloads	ollama (Mac, localhost:11434)	Lint, format, bash scripts, local validation — free + private
Runtime orchestration	OpenClaw	Route tools into agent workflows, gateway, auth
Repeatable procedure	Claude Skill	Encode durable operating knowledge (this file)

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":

Use-case	Why Gemini
Visual diff / screenshot comparison	2M-token vision context, sandbox testing
Whole-repo architecture mapping	Largest single-shot context window available
Multi-file stale-doc detection	Reads entire docs/ + src/ in one pass
Second-opinion code review of >5000-line diffs	Pro model handles size comfortably

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
• 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

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

Model	Use
Gemini Pro	architecture, whole-repo reading, security review, visual diff
Gemini Flash	quick review, smaller files, routine docs

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

Tool	Purpose
run	Launch a background AI CLI process
wait	Wait for one or more PIDs
peek	Watch short live output from a running worker
get_result	Fetch result for one worker
list_processes	List tracked workers
kill_process	Stop a stuck worker

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

Role	Command	Meaning
OpenClaw as MCP server	openclaw mcp serve	Claude or Codex talks to OpenClaw
OpenClaw as MCP client registry	openclaw mcp set/list/show/unset	OpenClaw stores outbound MCP servers

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

Tool count	Setting
< 10 tools	default usually fine
Many tools	ENABLE_TOOL_SEARCH=auto
Proxy / custom backend	configure explicitly if supported

---

10. Troubleshooting

Symptom	Likely cause	Fix
MCP server missing	Not registered or client not restarted	Run /mcp and claude mcp list
Gemini tool fails	Gemini CLI not authenticated	gemini auth login
Wrong Gemini package	Old guide used wrong package	Use @google/gemini-cli
ai-cli worker hangs	First-run prompt not accepted	claude --dangerously-skip-permissions once
claude -p says Not logged in after login	OAuth callback or credential persistence failed in sandbox	claude auth login --claudeai outside sandbox; verify auth status and claude -p
Claude login says success but status is false	Login metadata was written without a usable token	Capture --debug log; rerun auth outside sandbox
Multiple Claude installs	PATH/native/global mismatch	Compare which claude, versions, exact binaries; use one binary everywhere
OpenRouter free-tier rate-limit hit	50 req/day exceeded	Fall back to local ollama, or wait
OpenRouter model unavailable	Provider rate limit on that specific model	Use the fallback chain in §2 Rule 1
JSON parse error	Debug logs pollute stdout	Set MCP_CLAUDE_DEBUG=false
ESM import error	Old Node version	Use Node.js 20+
Agent runs forever	Worker stuck	peek, then kill_process
Too many tools	Tool overload	Enable tool search
OpenClaw cannot see server	Wrong config shape	Use openclaw mcp set or mcp.servers

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:

Repetitions	Action
1	Store in learnings.md
2–3	Add checklist item
4+	Promote into SKILL.md

---

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

Need	Use
One-time direct task	Claude Code (this session)
Generic worker reading or coding	OpenRouter Nemotron / MiniMax (per fallback chain)
Local-only lint, format, bash	ollama qwen3.5 (Mac)
Visual diff / screenshot comparison	Gemini Pro (Gemini-Analyzer)
Whole-repo architecture review	Gemini Pro (Gemini-Analyzer)
Multi-file stale-doc detection	Gemini Pro (Gemini-Analyzer)
Mechanical search-replace across many files	Codex CLI via ai-cli-mcp
Multiple independent worker tasks in parallel	ai-cli-mcp dispatch
Messaging or channel-based routing	OpenClaw
Judgment / content insertion / final synthesis	Claude Sonnet 4.6 + prompt cache
Repeated procedure to encode	Claude Skill
Missing capability	Custom MCP server

---

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:

Legacy path	New status
OpenClaw/MCP_ORCHESTRATION_SKILL.md	Redirect stub — points here
OpenClaw/MCP_ORCHESTRATION_SKILL_v2.md	Redirect stub — points here
OpenClaw/MCP-INSTALL-PLAN.md	Reference companion — kept for installation procedure
~/.claude/skills/mcp-orchestration/SKILL.md	User-level mirror — keep in sync via install -m 0644 bin/orama-system/mcp-orchestration/SKILL.md ~/.claude/skills/mcp-orchestration/SKILL.md (run from repo root after edits). For installing the MCP stack itself, see bin/orama-system/mcp-install/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.