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:
- Generate a new private key (saved to
./data/identity.json) - Mint a nametag on Unicity blockchain
- Publish Nostr binding for the nametag
- 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
-
User lists available games:
Tool: list_games -
User requests a game with their Unicity ID:
Tool: get_game Args: { "unicity_id": "alice", "game": "unicity-quake" } -
If no day pass, payment is requested. The user receives a payment request in their Unicity wallet.
-
User confirms payment:
Tool: confirm_payment Args: { "unicity_id": "alice" } -
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