MCP Ops

MCP Operations

mcporter is the fastest way to inspect and call any MCP tool directly from terminal. FastMCP is available system-wide: fastmcp --version (v3.2.4) Skill hierarchy: mcp-builder (build) → fastmcp-deploy (deploy) → mcp-ops (operate + recover) DITEMPA BUKAN DIBERI

Overview

Unified MCP operations covering three domains:

1. General MCP Ops — mcporter CLI for inspecting, calling, and debugging MCP servers from terminal.
2. Federation MCP Ops — FastMCP build/deploy/operate across federation organs.
3. MCP Lifeguard — Health probe and auto-recovery for constitutional federation MCP servers.

arifOS-ACT Embedding

Before using this skill on any mutating, irreversible, or high-blast-radius task:

1. ART — Attune (what is the real task?), Recognize (what class of power?), Test (fit · authority · evidence · blast · reversible).
2. Kernel — Route to arifOS for F1–F13 judgment if action class is Maker/Messenger/Mutator/Destroyer/Sovereign.
3. ACT — Apply narrow, Constrain scope, Trace witness, STOP before corruption.
4. Receipt — Leave evidence of what changed, why, and under whose authority.

When to Use

• Inspect, list, or call tools on any federation organ via mcporter.
• Build or extend a Python MCP server with FastMCP.
• Test a server locally before client wiring or deployment.
• Run ad-hoc HTTP or stdio MCP connections without permanent config.
• Check federation MCP health and tool availability.
• An MCP server returns connection refused, timeout, or 5xx.
• OpenClaw logs show [bundle-mcp] failed to start server.
• Model fallback chain is failing (DeepSeek 402, Kimi unknown model, Ollama cold-start).
• Need a federation MCP status dashboard.
• Generate CLI wrappers or TypeScript clients from a server spec.

When NOT to Use

• Do not use for production deployment without fastmcp-deploy or site-architecture skills and arifOS judgment.
• Do not mutate live federation servers (restart, config change, port binding) without arifOS F1–F13 clearance.
• Do not run untrusted MCP servers outside the arifos-untrusted-sandbox skill.
• Do not hardcode secrets in server code or client configs; use env vars / SOPS.
• If the target organ is degraded or unknown → run arifos-act and escalate to health triage.

Section 1: mcporter CLI

mcporter is pre-installed on af-forge at /usr/bin/mcporter v0.9.0.

Discovery

mcporter list                                    # list all known servers
mcporter list arifOS --schema                    # list tools + schemas for one server
mcporter list --http-url http://localhost:8081/mcp --name geox  # ad-hoc HTTP
mcporter list --stdio "npx -y @modelcontextprotocol/server-filesystem" --name fs

Call Tools

mcporter call arifOS.arif_measure mode=health    # call with key=value
mcporter call geox.geox_well_analyze_log well_id=MAHA-1 depth_top=1500 --output json
mcporter call well.well_validate_vitality --output json
mcporter call geox.geox_well_analyze_log --args '{"well_id": "MAHA-1", "depth_top": 1500}'  # JSON args
mcporter call "geox.geox_prospect_evaluate(well_id='MAHA-1')"  # function syntax

Federation MCP Servers

arifOS MCP    → arifOS        (7 canonical tools, F1-F13)
GEOX          → geox          (28+ tools, earth intelligence) ✅ LIVE
WEALTH        → WEALTH        (20+ tools, capital intelligence)
WELL          → WELL          (17+ tools, human readiness)
A-FORGE       → a-forge-mcp   (29 tools, execution engine)
AAA           → aaa-a2a       (A2A gateway + cockpit)
OpenClaw GW   → openclaw      (A2A mesh)

Daemon

mcporter daemon start
mcporter daemon status
mcporter daemon stop

Config / Auth / Codegen

mcporter config list
mcporter auth <server>
mcporter generate-cli --server geox
mcporter emit-ts <server> --mode client

Section 2: FastMCP Federation Build/Deploy/Operate

Install / Verify Tooling

uv add "fastmcp[tasks]==3.4.2"          # in a federation repo
pip install --break-system-packages "fastmcp[tasks]==3.4.2"  # system-wide
fastmcp --version                       # expect 3.4.2

Build a FastMCP Server

fastmcp scaffold --template api_wrapper --name "My API" --output ./my_server.py

Implement tools following federation conventions:

from fastmcp import FastMCP
from pydantic import BaseModel

mcp = FastMCP("my-server")

class CustomerOutput(BaseModel):
    id: str
    name: str
    segment: str
    confidence: float

@mcp.tool()
def get_customer(customer_id: str) -> CustomerOutput:
    """Fetch customer by ID with confidence score."""
    ...

Test Locally

fastmcp inspect my_server.py:mcp
fastmcp list my_server.py:mcp --json
fastmcp call my_server.py:mcp get_customer customer_id=cust_123 --json
fastmcp run my_server.py:mcp --transport streamable_http --host 127.0.0.1 --port 8000

Deploy

docker build -t my-mcp-server:latest .
fastmcp run my_server.py:mcp --transport http --port 8000 &
curl -s http://localhost:8000/mcp/v1/tools/list | jq '.tools[].name'

Adding MCP Server to Claude Code

Edit ~/.mcp.json:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Federation MCP Conventions

Section 3: MCP Lifeguard — Health Probe & Auto-Recovery

MCP Endpoint Map

Note: WEALTH and WELL return JSON-RPC errors on GET — this is normal. Connection refused or timeout is the real failure signal.

Quick Pulse Check

for port in 8088 8081 18082 18083 7072; do
  code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 3 "http://127.0.0.1:${port}/mcp" || echo "000")
  echo "Port $port: HTTP $code"
done

Deep Probe with Response Time

for port in 8088 8081 18082 18083 7072; do
  rt=$(curl -s -o /dev/null -w "%{time_total}" --max-time 5 "http://127.0.0.1:${port}/mcp" || echo "999")
  echo "Port $port: ${rt}s"
done

Auto-Restart Dead MCPs

mcp_map=(
  "8088:arifosmcp"
  "8081:geox_eic"
  "18082:wealth-organ"
  "18083:well"
)

for entry in "${mcp_map[@]}"; do
  port=${entry%%:*}
  container=${entry##*:}
  code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 "http://127.0.0.1:${port}/mcp" || echo "000")
  if [ "$code" = "000" ] || [ "$code" = "502" ] || [ "$code" = "503" ]; then
    docker restart "$container"
    echo "$(date -Iseconds) RESTARTED $container (port $port, code $code)"
  fi
done

Model Fallback Chain Monitor

# MiniMax
curl -s https://api.minimax.io/v1/models -H "Authorization: Bearer $MINIMAX_API_KEY" --max-time 5 | grep -q "MiniMax" && echo "MiniMax: OK" || echo "MiniMax: FAIL"

# DeepSeek
curl -s https://api.deepseek.com/v1/models -H "Authorization: Bearer $DEEPSEEK_API_KEY" --max-time 5 | grep -q "deepseek" && echo "DeepSeek: OK" || echo "DeepSeek: FAIL"

# Ollama local
curl -s http://127.0.0.1:11434/api/tags --max-time 5 | grep -q "qwen2.5:7b" && echo "Ollama: OK" || echo "Ollama: FAIL"

Pre-Warm Ollama (Avoid Cold-Start)

curl -s http://127.0.0.1:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen2.5:7b","prompt":"warmup","stream":false,"options":{"num_predict":1}}' \
  --max-time 30 > /dev/null
echo "Ollama warmed"

Alert Conditions

Lifeguard Rules

1. Never restart Vault999 — append-only ledger, human ack required.
2. Restart one MCP at a time — avoid federation cascade.
3. Log to ~/.openclaw/workspace/logs/mcp-lifeguard.log.
4. Disable dead models — don't let 402s burn event loop cycles.
5. Pre-warm Ollama on gateway startup if it's in fallbacks.

Troubleshooting

# MCP not responding — check endpoint
curl -s -X POST http://localhost:8081/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# GEOX MCP bridge — verify canonical tools
curl -s http://localhost:8081/tools | python3 -c \
  "import sys,json; d=json.load(sys.stdin); \
   print(f'GEOX categories: {len(d.get(\"categories\",[]))}')"

# Port conflict
ss -tlnp | grep <port>

# FastMCP version
fastmcp --version

Allowed Tools

Forbidden Actions

• NEVER expose a FastMCP server on 0.0.0.0 in production; bind to 127.0.0.1 and let Caddy terminate TLS.
• NEVER hardcode credentials; use environment variables or SOPS.
• NEVER call a mutating tool on a live federation organ without arifOS judgment.
• NEVER skip fastmcp inspect before wiring a new server into a client.
• NEVER treat a successful health check as authorization to act beyond observer class.
• NEVER restart Vault999 — append-only ledger, human ack required.
• Escalate to arifOS 888_JUDGE if the call involves deletion, deployment, secrets, or constitutional files.

Escalation Path

Consolidated 2026-08-26 from: FORGE-mcp-ops, FORGE-mcp-federation-ops, FORGE-mcp-lifeguard. AAA Skill Library — version 2.0.0