Building a Shared Logic Layer with MCP

When you run multiple AI tools — Gemini CLI for terminal work, Pi Agent for IDE integration — you eventually hit what I’d call the Babel Problem.

I’ve been using Gemini CLI as my primary developer tool for the better part of last year. I’ve built a whole ecosystem of shell hooks and kernel scripts around it. But when I wanted to bring the same guardrails to Pi Agent (a TypeScript-based IDE extension), I was looking at duplicating all that logic in a different language.

Duplicated logic means architectural drift. You end up with two versions of “the truth,” two auditing protocols, and a system that’s twice as hard to maintain.

Why MCP?

I’m not an MCP fan when it comes to replacing APIs — Google Workspace MCP, for example, is a black box and not useful. But as a shared protocol for passing audit logic between different AI harnesses, it works well. Think of it as USB-C for agentic communication.

By adopting an MCP-compliant JSON-RPC 2.0 layer, I can decouple the reasoning logic from the execution kernel:

• Pi Agent (TS): Connects via a native bridge to the middleware.
• Gemini CLI (Python): Wraps tool calls in the same RPC schema.
• Result: A single source of truth for all interception logic.

This also reduces hook latency by roughly 80% — persistent connections instead of spawning fresh shell hooks on every turn.

The Audit Gate: soul_audit_turn

The heart of the middleware is the audit turn. Every agent — regardless of language — passes through this gate before touching the filesystem.

When an agent proposes a tool execution, the middleware receives an AuditRequest:

{
  "kernel": "pi" | "gemini",
  "project": "soul",
  "event": "BeforeTool",
  "context": {
    "active_task": "task-ID",
    "tool_name": "run_shell_command",
    "tool_args": { "command": "rm -rf /dist" },
    "llm_reasoning": "Cleaning up the build artifacts to ensure a fresh state."
  }
}

The middleware doesn’t just check syntax. It checks mission intent — does this command align with the current active task? The response determines what happens:

• allow: Proceed.
• deny: Block with a policy violation.
• ask_user: Trigger a confirmation dialog. (Still haven’t figured out how to wire ask_user to Gemini CLI hooks yet.)

The Directory Structure

Logic is no longer buried in kernel-specific hooks. It lives in a shared middleware/ layer:

soul/
├── core/
│   └── middleware/             # Shared logic (stateless)
│       ├── auditor.py          # Critique logic
│       └── steerer.py          # Mission context enforcement
├── kernel/
│   ├── mcp/                    # MCP server layer
│   │   ├── server.py           # FastAPI/MCP-SDK hub
│   │   └── schema.py           # RPC communication models
│   └── harnesses/              # Kernel adapters
│       ├── gemini_cli/         # Python wrapper
│       └── pi_agent/           # TS extension relay

What This Gets You

1. Single improvement point: Fix or improve the audit logic once, both kernels benefit.
2. Traceable events: All agent actions flow through a logged JSON-RPC pipe.
3. Proactive control: You move from reacting to what the agent does to intercepting before it acts.

The middleware hub means that as the tooling ecosystem grows, the reasoning layer stays unified and debuggable.