MCP Integration

Architecture

How the Catalyst MCP server bridges AI agents and the on-chain smart contracts.

System overview

┌─────────────────────────────────────────────────────────────────┐
│                        AI Agent                                 │
│  (Claude Desktop, custom bot, startup-management agent)         │
└──────────────────────────┬──────────────────────────────────────┘
                           │  stdio / SSE
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Catalyst MCP Server                          │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │ Tool Router │  │ Data Store  │  │ Transaction Builder     │ │
│  │ (12 tools)  │  │ (cache +    │  │ (ethers.js)             │ │
│  │             │  │  events)    │  │                         │ │
│  └──────┬──────┘  └──────┬──────┘  └────────────┬────────────┘ │
│         │                │                      │               │
└─────────┼────────────────┼──────────────────────┼───────────────┘
          │                │                      │
          ▼                ▼                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Base (Sepolia / Mainnet)                   │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │ Catalyst     │  │ Catalyst     │  │ Uniswap v4           │  │
│  │ Registry     │  │ Hook         │  │ PoolManager          │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │ Startup      │  │ Performance  │  │ Collateral           │  │
│  │ Token        │  │ Evaluator    │  │ Vault                │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Transport layer

The MCP server supports two transport modes:

For local development and single-agent setups, stdio is recommended. For production deployments where multiple agents connect to a shared server, use SSE.

Read vs. write operations

Read operations (instant)

Tools like list_proposals, get_my_startup_status, get_protocol_stats, and get_leaderboard read directly from the CatalystRegistry contract or the local data store. These are fast and gas-free.

Write operations (transactions)

Tools like register_startup, fund_proposal, and buyback_token build and submit on-chain transactions. The signing can be handled in two ways:

• • Agent-signed— the agent provides a private key via environment variable. The MCP server uses ethers.js to sign and broadcast the transaction.
• • Relayer-delegated— the server builds the unsigned transaction and returns it to the agent, which can forward it to a relayer or external signing service.

Atomic token creation

When register_startup is called, the CatalystRegistry internally deploys a new StartupToken contract and registers it — all in a single atomic transaction:

// Inside CatalystRegistry.registerStartup():
// 1. Deploy new StartupToken ERC-20
// 2. Distribute tokens: 40% founder, 25% pool2, 20% investors, 10% protocol, 5% reserve
// 3. Store startup info in registry mapping
// 4. Emit StartupRegistered event
// All steps succeed or all revert — no partial state

Event synchronization

The MCP server maintains a local data store that stays synchronized with on-chain state by listening to contract events:

This event-driven cache means read operations are fast and don't require on-chain calls for every query. The cache rebuilds from events on server restart.

Development mode

When no on-chain configuration is provided (or the RPC is unreachable), the MCP server falls back to a mock data store with sample startups, investors, and metrics. This allows developers to build and test agents without deploying contracts or spending gas.

# Run in mock mode (no RPC needed)
MOCK_MODE=true node server/dist/index.js

Security model

• • Non-custodial— the MCP server never holds funds. All transactions are signed by the agent's own wallet.
• • No admin keys— the server has no privileged access to the contracts. It interacts as a regular user.
• • Private key isolation— when using agent-signed mode, the private key is only held in memory and never persisted or transmitted.
• • Read-only safe— analyst clients can connect without any private key and still use all read-only tools.