Sphere MCP Gaming Server

MCP (Model Context Protocol) server for the Unicity gaming platform. Provides LLM access to games with payment-gated day passes via Nostr.

Features

• Day Pass System: Users pay once for 24-hour access to all games
• Nostr Integration: Payment requests sent via Nostr protocol
• Unicity Blockchain: Uses nametags for identity and payment routing
• Auto Identity: Server creates its own blockchain identity on first run
• HTTP Transport: Supports both legacy SSE and modern Streamable HTTP

Available Games

ID	Name	Description
unicity-quake	Unicity Quake	Fast-paced multiplayer arena shooter
boxy-run	Boxy Run	Endless runner with blockchain rewards
unirun	Unirun	Unicity-native endless runner

MCP Tools

Tool	Parameters	Description
list_games	-	List all available games
check_access	unicity_id	Check access status and day pass validity
get_game	unicity_id, game	Get access to a specific game (initiates payment if needed)
confirm_payment	unicity_id, game (optional)	Wait for payment confirmation
get_wallet_balance	password	Get MCP wallet balance (admin)

All tools that require user identity take unicity_id as a parameter, making the API stateless and suitable for multi-user scenarios.

HTTP Endpoints

The server runs on HTTP (default port 3001) with two transport protocols:

Legacy SSE (MCP Inspector, older clients)

Endpoint	Method	Description
/sse	GET	Establish SSE stream, returns POST endpoint
/messages?sessionId=xxx	POST	Send JSON-RPC messages

Streamable HTTP (modern clients)

Endpoint	Method	Description
/mcp	POST	Send JSON-RPC requests
/mcp	GET	SSE stream for responses

Session ID is passed via mcp-session-id header.

Health Check

Endpoint	Method	Description
/health	GET	Returns { status, sseSessions, httpSessions }

Quick Start

1. Configure Environment

cp .env.example .env

Edit .env with required values:

# Required
MCP_NAMETAG=gaming-mcp
PAYMENT_COIN_ID=your_coin_id_here

2. Run with Docker Compose

docker compose up -d

The server will:

1. Generate a new private key (saved to ./data/identity.json)
2. Mint a nametag on Unicity blockchain
3. Publish Nostr binding for the nametag
4. Start listening for MCP connections

3. View Logs

docker compose logs -f

Testing the MCP

Option 1: MCP Inspector (Recommended)

The MCP Inspector provides a web UI to interact with the server:

# Start the server
npm run build && npm start

# In another terminal, connect inspector to HTTP endpoint
npx @modelcontextprotocol/inspector --url http://localhost:3001/sse

This opens a browser UI where you can call tools interactively.

Option 2: curl (Health Check)

curl http://localhost:3001/health

Option 3: Claude Desktop Integration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "gaming": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Example Workflow

1. User lists available games:

   Tool: list_games
   

2. User requests a game with their Unicity ID:

   Tool: get_game
   Args: { "unicity_id": "alice", "game": "unicity-quake" }
   

3. If no day pass, payment is requested. The user receives a payment request in their Unicity wallet.

4. User confirms payment:

   Tool: confirm_payment
   Args: { "unicity_id": "alice" }
   

5. On successful payment, user gets game URL and 24h access.

Configuration

Variable	Required	Default	Description
MCP_NAMETAG	Yes	-	Nametag for this MCP server
PAYMENT_COIN_ID	Yes	-	Coin ID for payments
MCP_PRIVATE_KEY_HEX	No	Auto-generated	Private key (hex)
NOSTR_RELAY_URL	No	wss://nostr-relay.testnet.unicity.network	Nostr relay
AGGREGATOR_URL	No	https://goggregator-test.unicity.network	Unicity aggregator
AGGREGATOR_API_KEY	No	(testnet key)	Aggregator API key
PAYMENT_AMOUNT	No	1000000000	Payment amount
DAY_PASS_HOURS	No	24	Day pass duration
PAYMENT_TIMEOUT_SECONDS	No	120	Payment timeout
DATA_DIR	No	./data	Data persistence directory
ADMIN_PASSWORD	No	Auto-generated	Admin password for wallet access
HTTP_PORT	No	3001	HTTP server port

Data Persistence

The server stores identity and nametag data in DATA_DIR:

• identity.json - Private key (keep this safe!)
• nametag-{name}.json - Minted nametag token

Mount this directory as a volume to persist across container restarts.

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

# Watch mode
npm run dev

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   LLM Client    │────▶│   MCP Server    │────▶│  Nostr Relay    │
│ (Claude, etc.)  │     │ (HTTP transport)│     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │                        │
                               ▼                        ▼
                        ┌─────────────────┐     ┌─────────────────┐
                        │    Unicity      │     │  User Wallet    │
                        │   Aggregator    │     │  (Sphere app)   │
                        └─────────────────┘     └─────────────────┘

License

MIT