MCP Server (AI Integration)

The Obelysk MCP server lets AI assistants --- Claude, Cursor, and other Model Context Protocol clients --- interact with the Obelysk Protocol on Starknet. It exposes 9 tools for querying on-chain state and executing transactions through natural language.

What is MCP?

The Model Context Protocol is an open standard that lets AI assistants call external tools. Instead of copying addresses and pasting into block explorers, you can ask your AI assistant to check your staking position, query the dark pool epoch, or even deposit into a privacy pool.

Installation

The MCP server runs as a local process that communicates over stdio.

cd sdk/typescript
npx ts-node src/mcp/index.ts

Claude Desktop Configuration

Add this to your Claude Desktop config file at ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "obelysk": {
      "command": "npx",
      "args": ["ts-node", "/path/to/sdk/typescript/src/mcp/index.ts"],
      "env": {
        "STARKNET_RPC": "https://starknet-mainnet.g.alchemy.com/starknet/version/rpc/v0_7/YOUR_KEY"
      }
    }
  }
}

For write operations (deposits, staking), add these optional environment variables:

{
  "env": {
    "STARKNET_RPC": "https://your-rpc-endpoint.com",
    "DEPLOYER_PRIVKEY": "0xYOUR_PRIVATE_KEY",
    "DEPLOYER_ADDRESS": "0xYOUR_ACCOUNT_ADDRESS",
    "VM31_RELAYER_URL": "https://vm31.bitsage.network"
  }
}

Without DEPLOYER_PRIVKEY, the server operates in read-only mode. All query tools still work.

Available Tools

Read-Only Tools

Tool	Description
`obelysk_balance`	Get encrypted balance for an address across protocol contracts (ConfidentialTransfer, DarkPool, PrivacyPool)
`obelysk_epoch_info`	Get current DarkPool batch auction epoch number, phase (Commit/Reveal/Settle/Closed), and trading pairs
`obelysk_staking_info`	Query staking position for an address --- staked amount, GPU tier, pending rewards
`obelysk_pool_stats`	Get Privacy Pool statistics --- total deposits, Merkle tree size, commitment count
`obelysk_vm31_status`	Check VM31 relayer health and batch processing status
`obelysk_trade_history`	Fetch recent OTC orderbook trades for a given trading pair
`obelysk_network_status`	Overall protocol health --- contract status, relayer connectivity, epoch state

Write Tools

Tool	Description
`obelysk_deposit`	Deposit tokens into a privacy pool (requires private key)
`obelysk_stake`	Stake SAGE tokens into the prover staking contract (requires private key)

Example Conversations

Once configured, you can interact with Obelysk through natural language:

Check staking position:

"What is my staking position on Obelysk for address 0x00740f...?"

The assistant calls obelysk_staking_info and returns your staked amount, tier, and pending rewards.

Query dark pool state:

"What phase is the Obelysk dark pool in right now?"

The assistant calls obelysk_epoch_info and tells you the current epoch number and phase.

Check protocol health:

"Is the Obelysk protocol healthy? Check all services."

The assistant calls obelysk_network_status and reports on contract status, relayer connectivity, and epoch state.

Next Steps

SDK Overview --- use the SDK directly in your TypeScript code
Privacy Architecture --- understand how the protocol works under the hood
Deployed Contracts --- all mainnet contract addresses