@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.