FORGE-mcp-federation-ops

MCP Federation Operations

Overview

Operate the federation's Model Context Protocol (MCP) surface: build FastMCP servers in Python, inspect and call tools via the fastmcp and mcporter CLIs, and route requests across arifOS, GEOX, WEALTH, WELL, and A-FORGE. This skill covers both construction (scaffold → implement → test → run) and runtime operations (discovery → health → direct tool calls).

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

• Build or extend a Python MCP server with FastMCP.
• Inspect, list, or call tools on any federation organ.
• Test a server locally before client wiring or deployment.
• Run ad-hoc HTTP or stdio MCP connections without permanent config.
• Generate CLI wrappers or TypeScript clients from a server spec.
• Check federation MCP health and tool availability.

When NOT to Use

• Do not use for production deployment without the 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.

Inputs

Procedure

Step 1: Install / Verify Tooling

# FastMCP CLI + library
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

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

Step 2: Build a FastMCP Server

# Scaffold from template
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."""
    ...

Step 3: 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

Step 4: Discover Federation Servers

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

Step 5: Call Federation Tools

# Key=value syntax
mcporter call arifOS.arif_ops_measure mode=health
mcporter call geox.geox_well_analyze_log well_id=MAHA-1 depth_top=1500 --output json

# JSON args
mcporter call geox.geox_well_analyze_log --args '{"well_id": "MAHA-1", "depth_top": 1500}'

# Function syntax
mcporter call "geox.geox_prospect_evaluate(well_id='MAHA-1')"

Step 6: Check Federation Health

curl -sf http://localhost:8088/health  | python3 -m json.tool   # arifOS
curl -sf http://localhost:8081/health                            # GEOX
curl -sf http://localhost:18082/health                           # WEALTH
curl -sf http://localhost:18083/health                           # WELL
curl -sf http://localhost:7071/health                            # A-FORGE

Step 7: Daemon / Config / Codegen (Optional)

mcporter daemon start
mcporter daemon status
mcporter daemon stop

mcporter config list
mcporter auth <server>

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

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.
• Escalate to arifOS 888_JUDGE if the call involves deletion, deployment, secrets, or constitutional files.

Output Format

## Skill Result: mcp-federation-ops

### Summary
One-paragraph summary of what was built, inspected, or called.

### Evidence
- Server/tool inspected: <name>
- Health status: <OK / DEGRADED / DOWN>
- Sample call result: <short JSON or summary>
- Schema compliance: <pass / fail / notes>

### Recommendations
- Next step (e.g., deploy, fix, escalate)
- Any drift or version mismatch found

### Escalations
- None / <list>

Escalation Path

Skill synthesized from: .claude/skills/mcp-ops.md, .codex/skills/fastmcp.md, .codex/skills/mcporter.md AAA Skill Library — version 1.0.0