Xcelsior GPU Cloud

Xcelsior MCP Server

Hosted Model Context Protocol server for the Xcelsior GPU platform.

Requires Node.js ^20.20.0 or >=22.22.0 (the pinned PostHog MCP beta no longer supports Node 18).

Quick start (local)

cd mcp

npm ci XCELSIOR_MCP_API_URL=http://127.0.0.1:8000 npm run dev

Liveness: GET http://localhost:8770/health Readiness: GET http://localhost:8770/readyz MCP endpoint: http://localhost:8770/mcp

Compare source declarations with production

npx tsx scripts/check-live-surface.ts /path/to/private/token-file

The file contains a bearer token or an agent-key JSON response. The checker authenticates, lists tools, and compares names, annotations and output-schema presence with the customer registry in this checkout. It never invokes a tool handler or prints the token. This gives monorepo-aware coverage when a source scanner cannot discover the registrations; it does not prove handler behavior.

Connecting

The canonical connector URL is `https://mcp.xcelsior.ca/mcp`.

Default path — OAuth consent (what humans use)

Paste that URL into Claude, ChatGPT, Grok, Copilot Studio, Cursor, or VS Code and press connect. The client discovers everything it needs on its own:

1. It calls /mcp with no credentials and gets 401 plus WWW-Authenticate: Bearer realm="xcelsior", resource_metadata="…".
2. It fetches /.well-known/oauth-protected-resource, which names the authorization server and the exact resource identifier.
3. It identifies itself — by CIMD (preferred: client_id is an HTTPS URL serving the client's own metadata), by RFC 7591 dynamic registration at /oauth/register, or with the pre-provisioned public client xcelsior-connector.
4. You sign in and approve the requested scopes on Xcelsior's own consent screen. Approval is remembered per client, per scope set, per resource, and is revocable in Settings → AI Agents.
5. It exchanges the code with S256 PKCE at /oauth/token (application/x-www-form-urlencoded) for a ~1h access token bound to https://mcp.xcelsior.ca/mcp, plus a 30-day refresh token.

No client secret is involved, and nothing has to be pasted by hand.

Automation path — client_credentials

For CI, scripts, and headless agents where no human is present to consent. Create a machine client in Dashboard → Settings → Connect AI Agents, then:

curl -s -X POST https://xcelsior.ca/oauth/token \

-H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=client_credentials' \ -d 'resource=https://mcp.xcelsior.ca/mcp' \ -d "client_id=$MCP_CLIENT_ID" -d "client_secret=$MCP_CLIENT_SECRET"

{

"mcpServers": { "xcelsior": { "url": "https://mcp.xcelsior.ca/mcp", "headers": { "Authorization": "Bearer YOUR_ACCESS_TOKEN" } } } }

client_credentials is fully supported and is not going away — it is simply not the front door for a person connecting an assistant.

Resource identifier

https://mcp.xcelsior.ca/mcp — the exact URL a user pastes, path included. Protected-resource metadata, the resource parameter on authorization and token requests, and the aud claim all carry that one value. Tokens issued before the migration carry the bare origin https://mcp.xcelsior.ca and remain valid until 2026-11-30, after which they are rejected like any other wrong-audience token.

Trust surfaces

One codebase, one image, two exposed surfaces (XCELSIOR_MCP_TOOL_PROFILE):

Operator tools are not registered at all under the customer profile, so they cannot appear in tools/list and cannot be called by name. A token without operator scopes never enumerates them even on the operator host.

Environment

MCP analytics

@posthog/mcp is pinned to 0.11.4 because its pre-1.0 API may change. When a PostHog project key is configured, the server instruments both hosted HTTP and STDIO MCP traffic and emits the standard $mcp_* lifecycle/tool events. The authenticated Xcelsior user_id is used as distinct_id (with OAuth subject and tenant id as machine-principal fallbacks), so calls remain grouped across the hosted service's stateless per-request server instances.

Analytics is metadata-only: Xcelsior removes tool arguments, tool results, and exception messages before send, disables GeoIP and exception fan-out, and does not inject PostHog's context or conversation_id arguments into the reviewed tool schemas. The Streamable HTTP transport uses JSON responses so the SDK can carry its signed Mcp-Session-Id token across replicas. The shared posthog-node client is flushed during graceful shutdown.

If MCP analytics identifies users, production must also set XCELSIOR_POSTHOG_PERSONAL_API_KEY and XCELSIOR_POSTHOG_PROJECT_ID for the privacy-deletion worker. Startup validation rejects identification without those deletion credentials.

Tools (v2)

• Discovery: list_available_gpus, get_spot_prices, get_pricing_reference, search_marketplace, list_tiers
• Compute: list_instances, get_instance, get_instance_logs, create_instance, cancel_instance, terminate_instance
• Billing: get_wallet_balance, estimate_job_cost, list_invoices
• Guardrails: should_i_run_this (estimate + wallet + optional max_hourly_cad)
• Workflows: run_training_job, schedule_under_budget
• Serverless: list_serverless_endpoints, create_serverless_endpoint, run_serverless_job, get_serverless_job_status
• Monitoring: watch_instance (poll status + telemetry + logs)
• Diagnostics: explain_instance_placement, simulate_instance_placement, get_instance_timeline, get_active_lease, get_mcp_action_status
• Operations (tenant): retry_instance, reconcile_instance

Operator profile only: get_scheduler_health, get_host_capacity, list_reconciliation_findings, drain_host, undrain_host, evict_host_workloads, retry_agent_command.

Company knowledge (optional, off by default): search and fetch, with OpenAI's exact schemas, over the documentation site, llms.txt, the pricing table, and live marketplace listings. Every result carries an absolute, human-openable URL and an internal id. Enable with XCELSIOR_MCP_COMPANY_KNOWLEDGE=1; it is deliberately not on for the base directory submission.

Resources: xcelsior://docs/llms, xcelsior://pricing/reference Prompts: cheapest-gpu-now, ca-fine-tune, serverless-inference

create_instance and create_serverless_endpoint always create a server-bound action plan first. confirm:true expresses intent but never replaces approval; execute with the returned plan_id after standing-policy or human approval. A confirmed call without a plan safely prepares a plan and returns approval_required. Host draining never evicts workloads; eviction has its own scope and action plan.

Stdio package (v2)

npx @xcelsior-gpu/mcp

Requires XCELSIOR_ACCESS_TOKEN. See mcp-cli/README.md.

Production deploy

Production promotion is blue/green across ports 8770/8771. Deployment runs readiness, bearer-authenticated protocol initialize, and tools/list against the standby before switching Nginx; a failure leaves the previous MCP serving.

Staging smoke

MCP_CLIENT_ID=... MCP_CLIENT_SECRET=... python3 scripts/mcp_smoke.py

Test with MCP Inspector

npx @modelcontextprotocol/inspector@latest

Point at http://localhost:8770/mcp with your MCP-audience Bearer token.