CapIX Router MCP

Open-source routing layer for CapIX Smart Route.

CapIX is the exchange. This repo is the public router skeleton that judges and developers can inspect: it reads a MongoDB-backed route book through MCP, uses Gemini to split compute jobs or inference prompts, and returns a priced allocation. Wallet settlement, treasury logic, private policy, Oracle host credentials, and production delivery stay inside the private CapIX protocol app.

What This Proves

• Compute routing: uploaded scripts are split across CPU and GPU capacity instead of running everything on the most expensive required lane.
• Inference routing: complex prompts are stripped of transport wrapper text, decomposed into subtasks, and routed across model sellers by price, latency, and reliability.
• MongoDB MCP integration: the route book is loaded from MongoDB Atlas through a hosted MongoDB MCP server.
• Gemini / Agent Builder integration: Gemini plans the allocation when configured; deterministic fallbacks keep demos reliable.
• Paid access boundary: production Smart Route can require a short-lived paid route key issued by the private CapIX app after a CPX deposit.

Repository Boundary

Included here:

• Router schemas, prompts, pricing math, fallbacks, and tests.
• Optional FastMCP tool server.
• JSON HTTP bridge used by the private CapIX app.
• Google Agent Builder / ADK agent definitions.
• Dockerfiles and Cloud Build configs for deployment.
• Demo route catalogs and sample workloads.

Not included here:

• CPX treasury keys or mint authority keys.
• Phantom wallet settlement code.
• CapIX private policy source.
• Oracle host agent credentials.
• Production SSH delivery and admin routes.
• Vercel private app environment values.

Project Layout

router/
  agent.py                 Compute job splitter and pricing estimator
  inference_agent.py       Prompt sanitizer, splitter, and inference route estimator
  mongodb_mcp_client.py    MongoDB MCP client with direct Mongo and offline fallbacks
  prompts.py               Strict JSON prompts for Gemini
  policy.py                Paid-route-key/private-policy boundary
  schemas.py               Route, allocation, and quote models

agent_builder/
  agents.py                Google ADK agents for compute and inference routing
  tools.py                 Agent tools backed by the router
  demo.py                  Local Agent Builder demo

server.py                  FastMCP tool server
http_server.py             JSON HTTP service for the private CapIX app
seed_nodes.py              Seeds compute and inference route catalogs into MongoDB
pull_capix_snapshot.py     One-shot private CapIX snapshot -> MongoDB sync
Dockerfile                 Router HTTP service container
Dockerfile.mongodb-mcp     Hosted MongoDB MCP service container
cloudbuild.*.yaml          Cloud Build image configs
examples/                  Demo workloads and local route snapshots
tests/                     Unit tests for routing, fallback, MCP, and agent tools

Local Quick Start

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python3 -m compileall .
pytest -q

Run a local JSON router:

CAPIX_ROUTER_PORT=8788 python http_server.py

In another terminal:

curl http://127.0.0.1:8788/health
curl http://127.0.0.1:8788/nodes | python -m json.tool | head -80

Run a local compute route:

curl -s http://127.0.0.1:8788/smart-route \
  -H "content-type: application/json" \
  -d '{
    "track": "compute",
    "language": "python",
    "code_content": "import numpy as np\nrows=[1,2,3]\nclean=[x for x in rows if x>1]\na=np.random.rand(1024,1024)\nb=np.random.rand(1024,1024)\nprint(np.dot(a,b).mean(), len(clean))",
    "setup_script": "numpy==2.1.3",
    "bundle_file_name": "demo.py"
  }' | python -m json.tool

Run a local inference route:

curl -s http://127.0.0.1:8788/smart-route \
  -H "content-type: application/json" \
  -d '{
    "track": "inference",
    "language": "prompt",
    "prompt_content": "Build an agent workflow for a support automation launch. Extract incident themes, plan API checks, draft escalation logic, and return a launch-review report."
  }' | python -m json.tool

MCP And HTTP Entry Points

This repo has two server modes.

FastMCP Tool Server

Use this when an MCP client wants tools directly:

python server.py

Tools exposed:

• get_node_pricing
• get_inference_routes
• split_and_route_job_tool
• split_and_route_prompt_tool

JSON HTTP Router

Use this for the private CapIX app and Cloud Run:

python http_server.py

Routes exposed:

• GET /health
• GET /nodes
• POST /smart-route
• POST /route

/smart-route accepts either compute or inference payloads and returns the same route response shape the CapIX Buy page displays.

Environment Variables

Start from .env.example. Keep real values out of Git.

Core router:

CAPIX_ROUTER_TOKEN=shared-private-app-token
CAPIX_REQUIRE_PAID_ROUTE_KEY=true
CAPIX_PRIVATE_POLICY_URL=https://capix.network/api/router/private-policy
CAPIX_PRIVATE_POLICY_TOKEN=shared-private-policy-token

MongoDB MCP:

MONGODB_MCP_URL=https://your-mongodb-mcp-service/mcp
MONGODB_MCP_TOKEN=optional-bearer-token
MONGODB_MCP_FIND_TOOL=find
MONGODB_MCP_DATABASE=capix_compute_db
MONGODB_MCP_NODES_COLLECTION=nodes
MONGODB_MCP_INFERENCE_COLLECTION=inference_routes

Gemini:

CAPIX_USE_VERTEX_AI=true
GOOGLE_CLOUD_PROJECT=your-google-cloud-project
GOOGLE_CLOUD_LOCATION=global
GEMINI_MODEL=gemini-2.5-flash

Local-only fallback:

GEMINI_API_KEY=your-local-gemini-api-key
MONGO_URI=mongodb://localhost:27017/

For the Google Cloud demo, prefer Vertex AI on Cloud Run and MongoDB MCP for route data. Do not set MONGO_URI on the router service if you want /nodes to report mongodb-mcp.

MongoDB Atlas Setup

Create a database:

capix_compute_db

Collections:

nodes             compute routes
inference_routes  model-provider routes

Seed demo-safe route books:

export MONGO_URI="<mongodb-atlas-driver-connection-string>"
python3 seed_nodes.py --prune

Expected seed size:

nodes             66 routes
inference_routes  60 routes

Smoke check:

python - <<'PY'
from router.mongodb_mcp_client import MongoDbMcpClient
client = MongoDbMcpClient()
compute = client.get_node_pricing()
inference = client.get_inference_routes()
print(compute.source, len(compute.nodes))
print(inference.source, len(inference.routes))
PY

Source meanings:

• mongodb-mcp: router is reading through hosted MongoDB MCP.
• mongodb-direct: router is using MONGO_URI directly.
• market-seed: router fell back to bundled demo catalogs.

One-Shot CapIX Snapshot Sync

If the private CapIX app exposes a signed snapshot endpoint, use this once to pull visible compute routes into MongoDB:

export CAPIX_SNAPSHOT_URL="https://capix.network/api/router/compute-snapshot"
export CAPIX_ROUTER_SYNC_TOKEN="<private-sync-token>"
export MONGO_URI="<mongodb-atlas-driver-connection-string>"
python3 pull_capix_snapshot.py

For a dry run:

python3 pull_capix_snapshot.py --dry-run

This script is intentionally one-shot. The public repo does not contain private capacity ingestion, host credentials, or settlement state.

Deploy To Google Cloud Run

Use two hosted services:

Private CapIX app on Vercel
  -> hosted CapIX Router HTTP service
  -> hosted MongoDB MCP service
  -> MongoDB Atlas capix_compute_db
  -> Gemini through Vertex AI

1. Enable APIs

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  secretmanager.googleapis.com \
  aiplatform.googleapis.com

2. Create Artifact Registry

export PROJECT_ID="<google-cloud-project-id>"
export REGION="us-central1"
export REPOSITORY="capix"

gcloud artifacts repositories create "$REPOSITORY" \
  --repository-format=docker \
  --location="$REGION" \
  --description="CapIX router images"

3. Create Secrets

printf '%s' "$MONGO_URI" | gcloud secrets create capix-mongo-uri --data-file=-
printf '%s' "$CAPIX_ROUTER_TOKEN" | gcloud secrets create capix-router-token --data-file=-
printf '%s' "$CAPIX_PRIVATE_POLICY_TOKEN" | gcloud secrets create capix-private-policy-token --data-file=-

If a secret already exists:

printf '%s' "$MONGO_URI" | gcloud secrets versions add capix-mongo-uri --data-file=-

4. Build And Deploy MongoDB MCP

gcloud builds submit \
  --config cloudbuild.mongodb-mcp.yaml \
  --substitutions _IMAGE="$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/capix-mongodb-mcp:latest"

gcloud run deploy capix-mongodb-mcp \
  --project="$PROJECT_ID" \
  --region="$REGION" \
  --image="$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/capix-mongodb-mcp:latest" \
  --set-env-vars="MDB_MCP_TRANSPORT=http,MDB_MCP_READ_ONLY=true,MDB_MCP_HTTP_HOST=0.0.0.0,MDB_MCP_HTTP_BODY_RESPONSE_TYPE=json" \
  --set-secrets="MDB_MCP_CONNECTION_STRING=capix-mongo-uri:latest" \
  --allow-unauthenticated

The router should call:

https://<mongodb-mcp-cloud-run-url>/mcp

For production, make the Atlas database user read-only and scope it to capix_compute_db. For stricter deployments, put Cloud Run IAM or an API gateway in front of the MCP service.

5. Build And Deploy CapIX Router

gcloud builds submit \
  --config cloudbuild.router.yaml \
  --substitutions _IMAGE="$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/capix-router-mcp:latest"

export MONGODB_MCP_URL="https://<mongodb-mcp-cloud-run-url>/mcp"

gcloud run deploy capix-router-mcp \
  --project="$PROJECT_ID" \
  --region="$REGION" \
  --image="$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/capix-router-mcp:latest" \
  --set-env-vars="MONGODB_MCP_URL=$MONGODB_MCP_URL,MONGODB_MCP_FIND_TOOL=find,MONGODB_MCP_DATABASE=capix_compute_db,MONGODB_MCP_NODES_COLLECTION=nodes,MONGODB_MCP_INFERENCE_COLLECTION=inference_routes,CAPIX_REQUIRE_PAID_ROUTE_KEY=true,CAPIX_PRIVATE_POLICY_URL=https://capix.network/api/router/private-policy,CAPIX_USE_VERTEX_AI=true,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global,GEMINI_MODEL=gemini-2.5-flash" \
  --set-secrets="CAPIX_ROUTER_TOKEN=capix-router-token:latest,CAPIX_PRIVATE_POLICY_TOKEN=capix-private-policy-token:latest" \
  --allow-unauthenticated

Smoke check:

export ROUTER_URL="https://<router-cloud-run-url>"
export CAPIX_ROUTER_TOKEN="<same-router-token>"

curl "$ROUTER_URL/health"
curl "$ROUTER_URL/nodes" \
  -H "authorization: Bearer $CAPIX_ROUTER_TOKEN" \
  | python -m json.tool | head -80

The /nodes response should include:

{
  "source": "mongodb-mcp"
}

Connect The Private CapIX App

Set these on the private Vercel project:

CAPIX_USE_SMART_ROUTER=true
CAPIX_ROUTER_URL=https://<router-cloud-run-url>/smart-route
CAPIX_ROUTER_TOKEN=<same-token-as-router>
CAPIX_ROUTER_KEY_SECRET=<private-route-key-derivation-secret>
CAPIX_PRIVATE_POLICY_TOKEN=<same-private-policy-token-used-by-router>

Private app flow:

Buyer opens Smart Route
  -> Phantom pays 0.01 CPX anti-abuse deposit
  -> private app mints a short-lived paid route key
  -> private app calls hosted CapIX Router
  -> router loads private policy and scans MongoDB MCP routes
  -> Gemini returns a CPU/GPU or model-provider split
  -> private app handles quote handoff and controlled delivery proof

The router should not run before the CPX deposit when CAPIX_REQUIRE_PAID_ROUTE_KEY=true.

Response Shape

Compute and inference routes return:

{
  "routing": {
    "analysis": "string",
    "allocation": [],
    "nodes": [],
    "source": "mongodb-mcp",
    "fallback_used": false,
    "warnings": []
  },
  "unoptimized_gpu_cost_usd": 0.45,
  "capix_optimized_cost_usd": 0.17,
  "percent_savings": "61%",
  "hold_cap_cpx": 1,
  "settled_cpx": 0.17,
  "released_cpx": 0.83
}

For compute, allocation uses line ranges:

{
  "node_id": "node-id",
  "label": "Vast.ai verified NVIDIA L4",
  "line_start": 33,
  "line_end": 42,
  "task_label": "numeric_kernels_and_tensor_operations",
  "reason": "Routed to GPU because this block contains tensor and matrix work."
}

For inference, allocation uses prompt segments:

{
  "node_id": "route-id",
  "label": "Foza provider pool / Mistral-Mixtral-8x22B",
  "line_start": 2,
  "line_end": 2,
  "task_label": "route_plan_decomposition",
  "segment_label": "Decompose the request into tool calls and ordering constraints.",
  "reason": "Planning-heavy prompts use a stronger reasoning lane."
}

Google Agent Builder / ADK

Install optional dependencies:

pip install -r requirements-agent-builder.txt

Run the local agent demo:

python -m agent_builder.demo

Agent definitions live in agent_builder/agents.py:

• CapIX_Compute_Router_Agent
• CapIX_Inference_Router_Agent
• CapIX_Router_Agent

The agents use tools from agent_builder/tools.py, which call the same router code used by the HTTP service. This keeps the demo honest: Agent Builder orchestrates a multi-step tool workflow, while MongoDB MCP supplies the route registry and Gemini performs the planning.

Demo Script

For a short recording, use DEMO_RECORDING_GUIDE.md.

Best sequence:

1. Show GET /nodes returning source: mongodb-mcp.
2. Open https://www.capix.network/buy?track=compute.
3. Choose Smart Route.
4. Pay the 0.01 CPX & Route deposit.
5. Show CPU/GPU allocation, quote, and savings.
6. Switch to inference Smart Route and show prompt decomposition across model sellers.
7. Explain that the public repo is the inspectable MCP/router layer; private settlement and delivery remain in CapIX.

Suggested judging line:

CapIX is the exchange. Smart Route is the routing edge: CPX payment unlocks a private route key, MongoDB MCP supplies the market depth, Gemini plans the split, and CapIX delivers compute or inference through the private app.

Safety Notes

• Never commit .env, Atlas passwords, Google credentials, CPX treasury keys, or private policy tokens.
• Keep MongoDB Atlas demo users read-only where possible.
• Keep CAPIX_REQUIRE_PAID_ROUTE_KEY=true in hosted demos so routing only happens after CPX deposit.
• Treat arbitrary uploaded code as untrusted. This repo returns routing plans; production execution belongs in isolated private infrastructure.

License

MIT. See LICENSE.