@colpero/mcp

@colpero/mcp

MCP server for the Colpero spatial network.

Three tools an LLM agent can call to read, navigate, and verify a physical scene:

Tool	What it does	Backend
query_scene	Look up objects in a scene by name, semantic type, or zone	GET /scenes/:id/search
get_path	Compute a navigable path between two nodes	POST /scenes/:id/path
verify_attestation	Verify an Ed25519-signed scan attestation (RFC-COL-001 Phase 1)	GET /scenes/:id/verify/:attestation_id

Add to Claude Code

claude mcp add colpero -- npx -y @colpero/mcp

Add to Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "colpero": {
      "command": "npx",
      "args": ["-y", "@colpero/mcp"]
    }
  }
}

Restart Claude Desktop. The three tools appear in the tool picker.

Configuration

Env var	Default	Notes
COLPERO_API_BASE	https://spatial-api-production-3a0d.up.railway.app	Point at your own deployment for local dev

x402 paywall

get_path is paid via x402 (USDC on Base Sepolia). On the hosted backend it returns HTTP 402 with payment instructions; client-side x402 payment is out of scope for v0.0.1, so the tool surfaces the 402 as an error.

query_scene and verify_attestation are free.

To run all three tools free against a local backend:

git clone https://github.com/lucatrevisanii/colpero
cd colpero/colpero-spatial-api
PAY_TO_ADDRESS= PORT=3099 npx ts-node src/server.ts
# then
COLPERO_API_BASE=http://localhost:3099 npx -y @colpero/mcp

Curl reference

The MCP server is a thin wrapper. Each tool maps 1:1 to a curl call.

# query_scene
curl "$API/scenes/lidar_room/search?q=desk"

# get_path
curl -X POST "$API/scenes/lidar_room/path" \
  -H "content-type: application/json" \
  -d '{"from":"obj_001","to":"obj_020"}'

# verify_attestation
curl "$API/scenes/lidar_room/verify/att_4b29f3861b9945c1a53b97d7"

Demo prompt

Once installed in Claude Code or Desktop:

Find the desk in scene lidar_room, then verify attestation att_4b29f3861b9945c1a53b97d7 and tell me whether the scan is genuine.

Claude calls query_scene then verify_attestation, returns the bbox plus the Ed25519 signature verification result. Both endpoints are free on the hosted backend; get_path is paywalled (see below).

License

MIT.