Architecture

System layers from MCP clients and the web UI down to Pocket Network RPC.

┌──────────────────────┐     ┌──────────────────────────────┐
│  MCP Clients         │     │  Next.js Frontend            │
│  Claude · Cursor     │     │  Chat · Agents · Automations │
└──────────┬───────────┘     └──────────────┬───────────────┘
           │ stdio                          │ REST / SSE
           ▼                                ▼
┌──────────────────────────────────────────────────────────┐
│                    FastAPI Backend                        │
│  /api/agents  /api/chat  /api/analytics                  │
│  /api/scheduled-tasks  /health                           │
│  ai_agent.py · pocket_rpc.py · scheduler.py (jobs loop)  │
└──────────────────────────┬───────────────────────────────┘
                           │ execute_tool() / chat()
                           ▼
┌──────────────────────────────────────────────────────────┐
│  backend/tools/TOOL_REGISTRY  (51 tools)                 │
│  balance · chain · compare · transact · analytics        │
└──────────────────────────┬───────────────────────────────┘
                           │ protocol dispatcher
                           ▼
┌──────────────────────────────────────────────────────────┐
│  Pocket Network Shannon Gateway                          │
│  https://{chain}.api.pocket.network                      │
│  52 chains · EVM · Cosmos · Solana · SUI · NEAR · TRON   │
└──────────────────────────────────────────────────────────┘

MCP adapter design

The MCP server is a thin stdio adapter over TOOL_REGISTRY. It does not re-route tools — call_tool delegates to the same execute_tool path the chat UI uses. This eliminates routing drift between surfaces.

RPC layer

PocketRPCClient dispatches by protocol family with response caching, exponential backoff, and relay logging. All chains use Pocket Network endpoints — no centralized provider API keys.

Automations scheduler

services/scheduler.py runs a background loop (~30s poll) that executes due rows from scheduled_tasks via AIAgentService.chat. Run history and approximate Pocket relay counts live in scheduled_task_runs. See the Automations guide.

Persistence

SQLite stores agents, encrypted wallet material, conversations, messages, relay logs, scheduled tasks, and task runs. Agent private keys are AES-256 encrypted at rest; only hashes of access tokens are stored.

Real-time streaming

Chat uses Server-Sent Events for token deltas, tool calls, and results. Transaction confirmations fan out through an in-process pub/sub broker to the chat UI and conversation stream endpoints.