Claude Code + AitherNode MCP: Giving an IDE Full Access to an Agentic OS

Most AI coding assistants talk to your code through a file system. They read files, write files, run shell commands. It works. But it's the equivalent of operating a nuclear reactor through a terminal — you can technically do everything, but you're missing the control panel, the gauges, the safety interlocks, and the 30 years of institutional knowledge that the operators carry in their heads.

AitherOS has 203 services, 12 AI agents, a GPU scheduler, a knowledge graph, a code graph with AST-level analysis, a pain-based self-healing system, and a full orchestration layer. All of that infrastructure is useless to an external IDE unless you build a bridge. So we built one — using the Model Context Protocol (MCP).

The result: Claude Code can now operate the entire AitherOS agentic stack through a single MCP server. Not as a toy demo. As the primary development interface. Every day.

What Is MCP and Why It Matters Here

MCP (Model Context Protocol) is an open standard from Anthropic for connecting AI assistants to external tools and data sources. It works via stdio — the AI spawns a local process, talks to it over stdin/stdout, and the process exposes a catalog of typed tools the AI can call.

The key insight: MCP turns your local infrastructure into first-class tools for the AI. Instead of the AI fumbling through shell commands to interact with your system, it gets named, documented, typed operations. ask_agent("demiurge", "explain the auth flow") instead of curl -X POST localhost:8001/chat -d .... The AI understands the tool semantics and uses them intelligently.

The AitherNode MCP Server: 300+ Tools, Zero Configuration

AitherNode (apps/AitherNode/mcp_server.py) is the MCP gateway for the entire AitherOS ecosystem. It uses auto-discovery — at startup, it scans all 48 tool modules in apps/AitherNode/tools/mcp/, inspects every public function with a docstring, extracts parameter types from Python type hints, and registers them as MCP tools. No manual registration. No schemas to maintain.

Add a new function to any mcp_*.py module with a docstring and type hints — it appears as a Claude Code tool on next restart. That's it.

The 48 modules cover every layer of the OS:

And 30+ more modules covering RBAC, social posting, Neocities deployment, mesh networking, Ollama management, context synthesis, gateway routing, specs, personas, and roadmap tracking.

Setup: 60 Seconds to Full Integration

The entire setup is one script:

# From the AitherOS directory:
python scripts/setup-claude.py

This generates two files:

1. .mcp.json — Tells Claude Code where the MCP server lives:

{
  "mcpServers": {
    "aitheros": {
      "command": ".venv/Scripts/python.exe",
      "args": ["apps/AitherNode/mcp_server.py"]
    }
  }
}

1. .claude/settings.local.json — Pre-approves the MCP tools so you don't get a permission prompt for every call:

{
  "permissions": {
    "allow": ["mcp__aitheros__*"]
  },
  "enableAllProjectMcpServers": true
}

Restart Claude Code. The MCP server starts automatically. 300+ tools are now available. No Docker, no API keys, no cloud dependency. It runs on your local Python venv and talks to your local AitherOS services over HTTP.

What It Looks Like in Practice

Here's what changes when Claude Code has access to the full AitherOS stack:

1. Agent Delegation: Ask the Expert

Instead of Claude Code trying to understand the codebase through grep and file reads, it can delegate to Demiurge (the code expert agent) who has the full context pipeline — CodeGraph, MemoryGraph, embeddings, conversation history:

# Claude Code calls:
mcp__aitheros__ask_agent(
  question="How does the effort routing work in AgentForge?",
  agent="demiurge",
  effort=5
)

# Returns structured JSON:
{
  "answer": "AgentForge routes through UCB + EffortScaler...",
  "files": [
    {"path": "lib/orchestration/AgentForge.py", "line": 142, "relevance": "high"},
    {"path": "lib/core/EffortScaler.py", "line": 67, "relevance": "high"}
  ],
  "code_refs": [
    {"name": "_get_llm_func", "file": "AgentForge.py", "start_line": 198, "type": "method"}
  ],
  "suggestions": ["Check effort tier mapping in agent_kernel.yaml"],
  "_agent": "demiurge",
  "_model": "aither-orchestrator"
}

The agent doesn't just answer — it returns exact file paths, line numbers, and code references that Claude Code can navigate to. It's like having a senior engineer on call who knows every line of the codebase.

2. CodeGraph: AST-Level Code Intelligence

Forget regex-based code search. CodeGraph parses the entire codebase into an AST-aware index with function signatures, call graphs, and semantic embeddings:

# Claude Code calls:
mcp__aitheros__codegraph_search(
  query="circuit breaker health check",
  limit=5
)

# Returns chunks with exact locations, signatures, and relevance scores:
{
  "results": [
    {
      "id": "lib/core/CircuitBreaker.py::check_health",
      "type": "method",
      "signature": "async def check_health(self, service: str) -> HealthStatus",
      "file": "lib/core/CircuitBreaker.py",
      "line": 234,
      "score": 0.92
    }
  ]
}

Then ask for the call graph — who calls this function, and what does it call:

mcp__aitheros__codegraph_get_context(
  chunk_id="lib/core/CircuitBreaker.py::check_health"
)
# Returns: callers, callees, import chain, containing class

Claude Code now understands blast radius before making changes. Not through heuristics — through actual static analysis.

3. Forge: Autonomous Agent Dispatch

For complex tasks, Claude Code can spawn autonomous subagents that have their own ReAct loops, tool access, and identity:

mcp__aitheros__forge_subagent(
  task="Audit all FastAPI routes for missing auth middleware",
  agent_type="mr_robot",  # Security specialist
  effort=7,
  max_turns=15
)
# Mr. Robot runs autonomously: reads code, checks patterns,
# queries CodeGraph, writes a structured security report

Or dispatch multiple agents in parallel:

mcp__aitheros__forge_parallel(
  tasks=["Review auth module", "Check rate limiting", "Audit CORS config"],
  agent_type="auto",  # Atlas routes each to the best agent
  effort=5
)

4. Swarm Coding: 11 Agents on One Problem

For big features, invoke the full coding swarm:

mcp__aitheros__swarm_run_and_deliver(
  task="Implement a WebSocket-based live log viewer",
  language="python",
  effort=7
)
# Phase 1: Architect designs the solution
# Phase 2: 8 agents in parallel (3 coders, 2 testers, 2 security, 1 scribe)
# Phase 3: Reviewer consolidates
# Phase 4: Judge scores quality
# Phase 5: Sandbox tests the code
# Phase 6: Delivers results to inbox

Claude Code just dispatched 11 AI agents that each have their own LLM context, tools, and expertise domain. The output is tested, reviewed, and scored — all from a single MCP tool call.

5. System Awareness

Claude Code isn't blind to the infrastructure:

mcp__aitheros__get_system_status()
# Returns: running services, GPU state, health scores, active agents, pain levels

mcp__aitheros__get_system_snapshot(save_to_memory=True)
# Full system state saved to knowledge graph for future reference

When Claude Code suggests deploying a change, it already knows which services are running, which are degraded, and whether the GPU has headroom.

The Feedback Loop: Every Tool Call Teaches the System

This is the part that matters most and what makes MCP different from just wrapping shell commands.

Every MCP tool call flows through AitherOS infrastructure. That means:

• Strata ingestion — Every tool call is logged and indexed for analytics
• Memory graph — Agent responses are stored as episodic memories that improve future context
• Training data harvesting — Real tool-call patterns feed ToolGraph's NanoGPT predictor
• FluxEmitter events — Tool calls emit typed events that trigger downstream reactions
• Pain system — Failed calls contribute to service health scores and trigger self-healing

When Claude Code calls ask_agent, the question flows through the full 12-stage ContextPipeline. That means CodeGraph context, MemoryGraph memories, live FluxEmitter state, and OS baseline anomaly scores are all injected into the agent's system prompt before it answers. The agent isn't just reading files — it's reasoning with the full cognitive apparatus of the OS.

Built-in tools bypass all of that. A grep finds text. An MCP tool call that reaches Demiurge finds text, understands its call graph, checks what changed recently, and remembers what the user asked about it last week.

The Auto-Discovery Engine

The MCP server's auto-discovery deserves its own section because it's what makes this maintainable at scale. Here's the registration logic:

# mcp_server.py — auto-discovery loop (simplified)
for module in mcp_package.__all__:  # 48 modules
    for func_name, func in inspect.getmembers(module, inspect.isfunction):
        if func_name.startswith("_"):
            continue  # Skip private functions
        if not func.__doc__:
            continue  # Must have a docstring

        # Extract params from type hints
        sig = inspect.signature(func)
        params = {}
        for param_name, param in sig.parameters.items():
            params[param_name] = infer_json_type(param.annotation)

        TOOLS[func_name] = {
            "fn": func,
            "description": func.__doc__.strip().split("\n")[0],
            "params": params,
        }

Convention over configuration. Any public function with a docstring in any mcp_*.py file becomes a tool. The docstring's first line becomes the tool description. Type hints become the parameter schema. No decorators, no registration calls, no YAML schemas.

To add a new tool to Claude Code's toolkit, a developer writes a normal Python function:

async def check_vram_usage() -> str:
    """Get current GPU VRAM usage across all loaded models."""
    # ... implementation ...

Restart the MCP server. Claude Code can now call mcp__aitheros__check_vram_usage().

Routing: When to Use MCP vs. Built-In

We established hard routing rules in our CLAUDE.md instructions to ensure Claude Code uses MCP tools by default:

Built-in tools are allowed as fallbacks when Genesis isn't running or for trivial single-line edits. But the default path is always through MCP — because that's where the learning loop lives.

What This Changes

Before MCP integration, Claude Code was a very smart text editor. It could read and write code, run tests, and use git. Impressive, but fundamentally limited to file-system-level operations.

After MCP integration, Claude Code is an AitherOS operator. It can:

• Delegate research to specialized agents who have deep domain knowledge
• Query a code graph with AST-level precision instead of regex-based search
• Spawn autonomous subagents for complex multi-step investigations
• Launch 11-agent coding swarms for large features
• Store and recall memories across sessions
• Monitor system health, GPU state, and service availability
• Deploy infrastructure, manage security, and trigger chaos testing
• Generate images, analyze voice, and process video through perception agents
• Publish to Neocities, post to social platforms, and manage roadmap items

The gap between "AI coding assistant" and "AI development platform" is exactly the gap between talking to files and talking to an operating system. MCP bridges it.

Live Demo: 5 Agents + 11-Agent Coding Swarm

Theory is nice. Here's what actually happened in a single Claude Code session on March 4, 2026. No mock data, no staged outputs — real agents running on an RTX 5090 through the production LLM stack.

Agent Delegation: 5 Agents, 5 Domains

We fired ask_agent at five different agents in parallel. Each has its own identity, persona, and capability set loaded from config/agent_cards.yaml:

Atlas identified 131+ services across 10 layers, reporting 10 healthy and 5 unhealthy. Hydra flagged tight coupling and long method chains. Athena auto-elevated to agentic mode — the EffortScaler detected a security query and gave her full tool access, scoring 0.96 (perfect) on the evaluation trace. All responses came back as structured JSON with file paths and code refs.

Swarm Coding: 11 Agents on a Real Bug

During the demo, we discovered a real bug: test_animation_physics.py called sys.exit(1) at module level, which crashed the entire pytest suite with an INTERNALERROR. Zero tests could run.

We threw the 11-agent coding swarm at the root cause:

mcp__aitheros__swarm_code(
  task="Fix pyproject.toml testpaths: currently testpaths = ['tests'] "
       "but actual test directory is dev/tests/. Change to dev/tests.",
  language="python",
  effort=7
)

# Swarm pipeline: ARCHITECT -> 8 parallel agents -> REVIEW -> JUDGE
# Total time: 219 seconds

What 11 Agents Produced

The swarm was deliberately over-engineered for a config fix — the point was demonstrating the pipeline, not the patch. In production, you'd aim it at features that actually warrant 11 agents: new service implementations, security refactors, or cross-cutting architectural changes.

Bugs Found During the Demo

The best part of the demo: the process of demonstrating the system revealed the system's own flaws. Three real bugs surfaced and were fixed in the same session:

The MCP bug was particularly ironic: we discovered it because we were using the tool in a live demo. The function signature said task, but the Genesis API expected problem. The MCP wrapper had never been tested end-to-end against the real endpoint. Dogfooding works.

The MCP SaaS Gateway: Opening the Stack to External Users

The same MCP server that powers Claude Code locally is now available as a hosted service. AitherNode Gateway (mcp.aitherium.com) exposes the full tool catalog over HTTP+SSE with tenant isolation, usage metering, and API key authentication:

// External users connect via:
// mcp.aitherium.com (Cloudflare tunnel -> AitherNode Gateway:8180)

// Authentication: ACTA API keys (aither_sk_live_*)
// Metering: Per-tool token costs (1-150 tokens per call)
// Plans: Explorer (free tier) -> Builder (pro) -> Enterprise

// Same 300+ tools, same agent delegation, same swarm engine
// But with tenant isolation, rate limiting, and usage billing

The gateway reuses every internal module. The difference is the auth layer (gateway/auth.py validates ACTA keys and checks token balance) and the metering layer (gateway/metering.py deducts per-tool costs). Internal calls skip both.

The Numbers

Try It Yourself

If you have a Python-based service ecosystem, you can build the same thing. The pattern is:

1. Write Python functions with docstrings and type hints
2. Have those functions call your services over HTTP
3. Auto-discover them with inspect at MCP server startup
4. Point Claude Code at the MCP server via .mcp.json
5. Write routing rules in CLAUDE.md so the AI prefers your tools

The MCP protocol is open. The auto-discovery pattern is general. What makes AitherOS unique isn't the bridge — it's what's on the other side: 203 services, a full cognitive pipeline, and agents that actually know your code.

Claude Code was already the best AI coding assistant. Now it has an operating system behind it.