MCP Server

What is MCP

The Model Context Protocol (MCP) lets AI clients call external tools in a standardized way. The core.today MCP server reuses the exact same credit-deduction and usage-logging path as the REST API — from model search through prediction creation and polling.

Authentication

Authenticate with either header — there is no functional difference.

X-API-Key: cdt_your_api_key

Authorization: Bearer cdt_your_api_key

Connection check

After installing, ask your client (e.g. Claude): "What's my core.today balance?" — get_balance is free and read-only, so it responds immediately and proves auth worked end to end.

To verify without a client, call tools/call directly with curl:

curl -X POST https://api.core.today/v1/mcp \
  -H "X-API-Key: cdt_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "get_balance", "arguments": {} }
  }'

Tool reference

All 9 tools operate within the calling API key's permission scope. The cost badge shows what's consumed: credits deducted, storage quota only, or nothing (rate limit only).

Workflow example

The typical generation flow is search → check schema → preview cost → create → poll.

1. search_models to find a model matching your requirements.
2. get_model_schema to check the input schema and exact pricing.
3. estimate_credits to preview the cost before running (no side effects).
4. create_prediction to start the job — credits are deducted up front and a job_id is returned.
5. Poll get_prediction(job_id) every 2-5 seconds until status is completed/failed/canceled.

// 1) search_models
search_models({ query: "product photo background removal" })

// 2) get_model_schema — inspect the chosen model's input schema
get_model_schema({ model_id: "<chosen model_id>" })

// 3) estimate_credits — preview cost, no side effects
estimate_credits({ model: "<chosen model_id>", input: { ... } })

// 4) create_prediction — spends credits, returns job_id
create_prediction({ model: "<chosen model_id>", input: { ... } })
// → { "job_id": "job_xxx", "status": "processing", ... }

// 5) get_prediction — poll every 2-5s until terminal status
get_prediction({ job_id: "job_xxx" })
// → { "status": "completed", "output_files": [ { "object_key": "...", "url": "..." } ] }

Choosing a file input method

When a model input needs a file, pick the method that fits your situation.

Error codes

When a tool call fails, the ToolError message is formatted as "code: message". Agents should branch on the code before the colon — the message is a human-readable description and its wording may change.

insufficient_credits: Required 12.50, available 3.20
rate_limited: per_minute limit reached (60/window). Retry after 42s.
not_found: model 'xyz/bad-model' not found. Try search_models first.
validation_error: input.prompt: field required
internal_error: unexpected server error (logged)

Limits

• Rate limiting: Read-only tools (search_models, get_prediction, etc.) consume 1 unit of the API key's per-minute budget per call. create_prediction already runs rate limiting on the prediction path itself, so the gate doesn't count it separately — no double charge. The initialize/tools/list handshake isn't charged.
• Stateless: The server runs stateless Streamable HTTP (any of several ECS tasks behind the ALB can answer). GET isn't supported and returns 405 — only POST/DELETE are allowed.
• Output URL expiry: The url in output_files returned by create_prediction/get_prediction is a signed, expiring URL. object_key is the durable identifier — store it and re-sign later when needed.
• import_file_from_url limits: File size is capped at 50MB, and private/internal network addresses are blocked (SSRF prevention).
• LLM chat: Chat-style LLM calls (OpenAI/Anthropic-compatible) go through a separate LLM gateway (/llm/openai/v1, /llm/anthropic/v1), not the MCP tools.