MCP Cell Server — sovereign live observation surface¶

How external observers (Claude Code, IDEs, agents) read the live cell¶

Status: v0.1 — read-only by default. Five tools exposed over JSON-RPC stdio (Model Context Protocol).

Related pages: Directive-Architecture · Franklin-Consciousness-MQ

1. Why¶

The cell exposes NATS on 127.0.0.1:4222 and writes constitutional state into substrate.sqlite and cell_identity.json. External observers (Claude Code sessions in this worktree, Xcode coding assistants, ops tooling) historically had to poll the filesystem to know what the cell was doing — that meant stale reads and incorrect conclusions when state was flapping between writes.

The sovereign MCP server gives observers a single, in-tree, no-third-party-deps protocol channel to read live cell state on demand. Read-only by default. No write tools in v0.1.

2. Architecture¶

Swift executable target GaiaCellMCPServer in cells/xcode/Sources/GaiaCellMCPServer/
JSON-RPC 2.0 over stdio (Model Context Protocol)
No third-party Swift packages. Uses sqlite3 CLI subprocess for substrate queries; raw POSIX sockets for NATS probe; Foundation for file I/O.
Single-threaded stdio loop. Each request is handled synchronously; stderr is the log channel so the protocol channel stays clean.
Registered to Claude Code via the project-level .mcp.json at the worktree root. Any Claude Code session opened in this directory picks it up automatically on session start.

3. Tools exposed (v0.1)¶

All tools are read-only and bounded.

Tool	Inputs	Returns
`cell_status`	—	Process list (Franklin/VQbitVM/FranklinConsciousnessService), full `cell_identity.json`, `tau_sync_state.json`, NATS port 4222 status, substrate file size, last directive timestamp.
`substrate_read`	`sql` (required, must start with `SELECT` or `WITH`; no semicolons), `limit` (default 50, max 500)	Header-prefixed JSON-mode sqlite3 output
`read_log`	`name` (basename only, no path traversal), `tail_bytes` (default 4096, max 65536)	Tail bytes from `~/Library/Logs/GaiaFTCL/<name>`
`causal_chain`	`directive_sha256` (must be 64-char hex)	Full `directive_causal_chains` view rows for that directive
`nats_ping`	—	`OPEN` / `closed` for `127.0.0.1:4222`

4. Security model¶

The MCP server is sovereign — no third-party SDK. Input validation lives in the server itself:

Substrate: refuses anything not starting with SELECT or WITH. Refuses semicolons (blocks stacked statements). All queries get an automatic LIMIT n appended.
Logs: refuses any name containing /, .., or leading .. Restricted to ~/Library/Logs/GaiaFTCL/.
Causal chain: refuses any non-64-char or non-hex directive_sha256 — blocks SQL injection through this path.
No write tools. A future write surface would go through the directive architecture (sealed receipts, operator countersign), not the MCP server.

5. Configuring¶

The project ships .mcp.json at the worktree root:

{
  "mcpServers": {
    "gaia-cell": {
      "command": "/path/to/cells/xcode/.build/arm64-apple-macosx/debug/GaiaCellMCPServer",
      "args": [],
      "env": {}
    }
  }
}

After running swift build --product GaiaCellMCPServer (which produces the binary at the path above), any Claude Code session opened in this worktree will see the mcp__gaia-cell__* tool family.

For other MCP clients (Cursor, custom agents), the same binary and config snippet apply.

6. Protocol handshake¶

The server implements the standard MCP stdio protocol. Verifiable from any shell:

BIN=cells/xcode/.build/arm64-apple-macosx/debug/GaiaCellMCPServer

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}' | "$BIN"
# → {"id":1,"jsonrpc":"2.0","result":{"capabilities":{"tools":{}},"protocolVersion":"2024-11-05","serverInfo":{"name":"gaia-cell","version":"0.1.0"}}}

tools/list:

printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | "$BIN" | tail -1

Live cell snapshot:

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cell_status","arguments":{}}}' \
  | "$BIN"

7. Future tools¶

When the outbound mediation architecture lands and nats_request becomes safe to expose, the v0.2 tool set will include:

nats_request(subject, payload, timeout_ms) — publish to NATS and wait for reply
directive_history — paginated read of user_directives
franklin_response_tail — paginated read of franklin_responses
(Write tools remain prohibited until they go through the directive architecture's sealed-receipt flow.)

8. Files¶

Source: cells/xcode/Sources/GaiaCellMCPServer/main.swift
Package wiring: cells/xcode/Package.swift (executable target GaiaCellMCPServer)
Project MCP config: .mcp.json at worktree root

Federation-cosigned

This page's source is sealed in the GaiaFTCL federation manifest — page SHA-256 483c238e7b5a2e62…, manifest witness a090592e0609adc8…, signed 2026-06-02T18:58:22Z by cell gaiaftcl-mac-cell. Verify with gaiaftcl wiki sign --all and compare wiki-all-signatures.json.