Imagine MCP

Production-oriented remote MCP service for xAI image generation, image editing, video generation, and text-to-speech. It exposes one Vercel Function at api/mcp.ts using the MCP TypeScript SDK's Streamable HTTP handler.

Every billable result is copied from xAI into an immutable Vercel Blob object. Clients receive the persistent public Blob URL, never the temporary xAI URL. Tests use mocked HTTP and in-memory storage only; they make no external or billable calls.

The service is designed as the render boundary for the overnight crew. Only that crew's Render bot should receive this MCP connection.

Tools

Image models: grok-imagine-image-2.0, grok-imagine-image, and grok-imagine-image-quality. Video models: grok-imagine-video-1.5 and grok-imagine-video.

Defaults are grok-imagine-image-2.0, grok-imagine-video-1.5, voice eve, and language auto. Tool schemas allow only the documented model IDs shown in the contracts above, so a newly introduced higher-priced model cannot bypass the reservation table. API-reported usage replaces the estimate when present.

Related MCP server: Sisif AI MCP Server

Architecture

flowchart LR
    B["Grok Bot<br/>Render only"] -->|x-mcp-secret| M["MCP endpoint<br/>auth + spend reserve"]
    M --> X["xAI API<br/>image / video / TTS"]
    X --> P[("Public Blob store<br/>persistent media")]
    X --> L[("Private Blob store<br/>append-only ledger")]
    P --> B

• api/mcp.ts — Vercel fetch entrypoint.

• src/server.ts — authentication, Origin policy, MCP registration, runtime wiring.

• src/xai.ts — xAI REST client, response validation, video polling and bounded retry.

• src/tools/ — one module per MCP tool.

• src/media.ts — bounded media downloads and immutable persistence.

• src/store.ts — Vercel Blob and in-memory adapters; production wires one public media store and one private ledger store.

• src/ledger.ts — append-only daily reservation/reconciliation events.

• src/pricing.ts — published fallback rates and usage-tick conversion.

• src/config.ts — fail-closed environment validation.

The MCP handler supports current per-request MCP traffic and the SDK's stateless legacy Streamable HTTP fallback. No session state is stored in a function instance.

Environment

Copy .env.example to your secret manager or Vercel project settings. Do not commit .env.

Required:

• MCP_SHARED_SECRET: 32–4096 characters. Every real MCP GET, POST, and DELETE request must send it as x-mcp-secret.

• XAI_API_KEY: server-side xAI key.

• DAILY_SPEND_LIMIT_USD: positive UTC-day xAI generation ceiling.

• A public Vercel Blob store for returned media:

  • MEDIA_BLOB_READ_WRITE_TOKEN, or

  • MEDIA_BLOB_STORE_ID with VERCEL_OIDC_TOKEN.

• A separate private Vercel Blob store for spend-ledger events:

  • LEDGER_BLOB_READ_WRITE_TOKEN, or

  • LEDGER_BLOB_STORE_ID with VERCEL_OIDC_TOKEN.

Vercel fixes a store's public/private mode when it is created, so one store cannot serve both roles. Reusing the same known token or store ID fails configuration validation. The obsolete BLOB_TOKEN and unprefixed BLOB_READ_WRITE_TOKEN variables are not used.

Optional:

• MCP_ALLOWED_ORIGINS: comma-separated exact HTTP(S) browser origins.

• MAX_IMAGE_BYTES, MAX_VIDEO_BYTES, MAX_AUDIO_BYTES: positive byte limits. Defaults are 25 MiB, 128 MiB, and 50 MiB.

Validate configuration without printing values or making network requests:

npm run doctor

Install and verify

Node.js 20 or newer:

./init.sh
./test.sh

Equivalent npm commands:

npm ci
npm run typecheck
npm test
npm run build

stop.sh is intentionally a no-op because this repository does not launch a background daemon. Vercel owns the production function lifecycle.

Deploy to Vercel

1. Create a Vercel project from this repository.

2. Connect two Vercel Blob stores: one Public store for media and one Private store for ledger events. Give them the environment prefixes MEDIA and LEDGER, or configure the explicit variables above.

3. configure every required environment variable above for the intended deployment environments.

4. Keep api/mcp.ts at /api/mcp. vercel.json requests an 800-second function, which requires Vercel Pro or Enterprise. This covers the ten-minute xAI video polling deadline plus response handling.

5. Deploy through your normal reviewed workflow.

This repository does not run deployment commands. Vercel Hobby currently caps functions at 300 seconds, so it is suitable for image/edit/TTS use but cannot reliably satisfy this synchronous generate_video contract. Do not present a Hobby deployment as video-ready.

Vercel Host and Origin behavior

The service does not hardcode a Host allowlist. Vercel deployment, preview, and custom-domain hostnames change independently, and Vercel validates routing and TLS before invoking the function. MCP_ALLOWED_ORIGINS controls the browser's Origin header, not the Vercel destination hostname.

Non-browser MCP clients normally omit Origin and are accepted after secret authentication. A request that sends Origin is rejected unless its exact origin is configured. This makes browser access opt-in. Allowed CORS preflights do not invoke MCP or xAI; the subsequent MCP request still requires x-mcp-secret.

Connect and smoke-test

Set shell variables without putting secrets into command history:

export MCP_URL='https://your-project.vercel.app/api/mcp'
read -s MCP_SHARED_SECRET
export MCP_SHARED_SECRET

Streamable HTTP initialize smoke request:

curl --fail-with-body --no-buffer \
  -X POST "$MCP_URL" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "x-mcp-secret: $MCP_SHARED_SECRET" \
  --data '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"initialize",
    "params":{
      "protocolVersion":"2025-06-18",
      "capabilities":{},
      "clientInfo":{"name":"curl-smoke","version":"1.0.0"}
    }
  }'

An unauthenticated check should return 401 without invoking a tool:

curl -i -X POST "$MCP_URL" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"ping"}'

For MCP Inspector:

npx @modelcontextprotocol/inspector

In Inspector, choose Streamable HTTP, enter $MCP_URL, and add the custom header x-mcp-secret. If Inspector sends requests directly from its browser UI, add that UI's exact origin to MCP_ALLOWED_ORIGINS; if it uses its local proxy, no browser Origin normally reaches the service. List tools before calling one. Tool calls are billable when configured with a real xAI key.

MCP clients that support remote headers should be configured with the same URL and a secret header sourced from their own environment or secret store. Never paste the xAI API key into an MCP client; only the shared MCP secret belongs in the client configuration.

Security notes

• Shared-secret comparison hashes both values and uses crypto.timingSafeEqual. Missing and malformed auth fail closed. Secrets, request headers, and upstream bodies are not emitted to application logs.

• Media returned by this service is intentionally public. Do not generate sensitive content. Reservation events in the separate private ledger store retain the submitted prompt/text with tool, model, estimate, and timestamp; reconciliation events add actual cost. Never put credentials in prompts.

• Caller-provided image_url values are passed to xAI as JSON and are never fetched by this service.

• The service fetches only URLs obtained from successful xAI responses. It requires HTTPS, rejects obvious local/private literal hosts, disables redirects, validates media MIME types, and enforces header and streaming size limits. DNS ownership of xAI-returned signed URLs remains part of the upstream trust boundary.

• DAILY_SPEND_LIMIT_USD is always required. See COST.md for reservation behavior and the documented serverless concurrency bound.

• Blob storage, egress, and Vercel execution charges are not reported by xAI and are outside the xAI generation ceiling.

Test policy

All tests inject mocked fetch implementations and an in-memory object store. They cover authentication, pricing and usage ticks, image request shapes, video polling/retry/timeout, binary TTS, media validation, Blob adapter options, and spend-cap behavior. No test reads XAI_API_KEY, contacts xAI, writes Vercel Blob, deploys, or incurs cost.

Report vulnerabilities through the private process in SECURITY.md, not a public issue.

License

MIT. Generated media remains subject to the provider terms and any rights in its source material.