Integrations

Carpe Diem reaches your tools in two ways:

• The MCP server (carpe-diem-mcp) gives an AI assistant — Claude Code, Claude Desktop, Cursor, Codex, VS Code, Zed… — around thirty Carpe tools: chat with any model, generate images, video, speech and music, search the web, compare prices, check your balance. The assistant decides when to call them; you stay in control of what it can spend.
• The API is OpenAI- and Anthropic-compatible. Any SDK, coding agent or chat app that lets you change the base URL can use Carpe models directly, with nothing to install.

You need an API key for both (or a funded wallet, for x402): create one in API → Keys, then add credits in API → Balance. Keys start with cdm_.

Choose your path

Two surfaces: /v1 and /router

Every integration below picks one of two base URLs. They take the same key and the same request bodies; they differ in who serves the request.

Full base URLs: https://carpe-diem.xyz/api/operator/v1 and https://carpe-diem.xyz/api/operator/router. Every response tells you who served it (X-Carpe-Route-Market) and what it cost; see the API reference.

MCP server

carpe-diem-mcp is an open-source (MIT) Model Context Protocol server. It runs on your machine, started by your assistant with npx, and talks to Carpe with your key. Source: github.com/Irdanwen/carpe-diem-mcp. Requires Node.js 20 or later.

What it gives your assistant

It also exposes three resources — carpe://models, carpe://pricing, carpe://markets — and three ready-made prompts:

• cheapest_model_for — shortlist models for a task, quote each on both surfaces, run the cheapest acceptable one, report cost and market.
• cost_report — balance, spend by model and by day, router savings, and a warning if the balance covers less than a week.
• private_inference — answer a confidential request on /v1 only, with a model Venice runs privately, and confirm it ran in the TEE.

Every result says what it cost and who served it (market, and whether it was a TEE). Tools that exist on both surfaces take a route argument: "carpe" (/v1, the default) or "router" (/router).

Spending stays under your control

The server prices every paid call before sending it — from free quotes — and refuses it locally, without calling Carpe, when it would exceed:

• CARPE_MAX_PER_CALL_USD — per call (default 0.50), or
• what is left of CARPE_MAX_SPEND_USD — per session (default 5).

carpe_session_spend shows the tally. CARPE_READ_ONLY=1 removes every tool that can spend or change anything. If a key leaks, carpe_revoke_this_key (with confirm: "REVOKE") disables it at once. carpe_topup_link returns a checkout link for a human to open: the assistant never pays by card.

Paid calls are retried only when Carpe certainly did not run them (rate limit, capacity), so a retry never bills twice.

Install

Pick your client. Each snippet starts the server with npx; replace cdm_your_key with your key. Then restart the client (or reload its MCP servers) and check it works by asking: "Call carpe_status."

# Available in every project (--scope user). Use --scope project to share it via .mcp.json.
claude mcp add carpe --scope user \
  --env CARPE_API_KEY=cdm_your_key \
  --env CARPE_MAX_SPEND_USD=5 \
  -- npx -y carpe-diem-mcp

// Settings → Developer → Edit Config
// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "carpe": {
      "command": "npx",
      "args": ["-y", "carpe-diem-mcp"],
      "env": { "CARPE_API_KEY": "cdm_your_key", "CARPE_MAX_SPEND_USD": "5" }
    }
  }
}

// ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (this project)
{
  "mcpServers": {
    "carpe": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "carpe-diem-mcp"],
      "env": { "CARPE_API_KEY": "${env:CARPE_API_KEY}", "CARPE_MAX_SPEND_USD": "5" }
    }
  }
}

// .vscode/mcp.json — VS Code asks for the key once and stores it securely
{
  "inputs": [
    { "type": "promptString", "id": "carpe-key", "description": "Carpe Diem API key (cdm_…)", "password": true }
  ],
  "servers": {
    "carpe": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "carpe-diem-mcp"],
      "env": { "CARPE_API_KEY": "${input:carpe-key}", "CARPE_MAX_SPEND_USD": "5" }
    }
  }
}

# ~/.codex/config.toml — or: codex mcp add carpe --env CARPE_API_KEY=cdm_your_key -- npx -y carpe-diem-mcp
[mcp_servers.carpe]
command = "npx"
args = ["-y", "carpe-diem-mcp"]
env_vars = ["CARPE_API_KEY"]   # passes your shell's CARPE_API_KEY through
 
[mcp_servers.carpe.env]
CARPE_MAX_SPEND_USD = "5"

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "carpe": {
      "type": "local",
      "command": ["npx", "-y", "carpe-diem-mcp"],
      "enabled": true,
      "environment": { "CARPE_API_KEY": "{env:CARPE_API_KEY}", "CARPE_MAX_SPEND_USD": "5" }
    }
  }
}

// ~/.gemini/settings.json (or .gemini/settings.json in a project).
// Gemini CLI hides inherited variables named *KEY*: declare the key here.
{
  "mcpServers": {
    "carpe": {
      "command": "npx",
      "args": ["-y", "carpe-diem-mcp"],
      "env": { "CARPE_API_KEY": "$CARPE_API_KEY", "CARPE_MAX_SPEND_USD": "5" }
    }
  }
}

// Zed settings.json
{
  "context_servers": {
    "carpe": {
      "command": "npx",
      "args": ["-y", "carpe-diem-mcp"],
      "env": { "CARPE_API_KEY": "cdm_your_key", "CARPE_MAX_SPEND_USD": "5" }
    }
  }
}

// Cline → MCP Servers → Configure MCP Servers
{
  "mcpServers": {
    "carpe": {
      "command": "npx",
      "args": ["-y", "carpe-diem-mcp"],
      "env": { "CARPE_API_KEY": "cdm_your_key", "CARPE_MAX_SPEND_USD": "5" },
      "disabled": false
    }
  }
}

# ~/.config/goose/config.yaml
extensions:
  carpe:
    name: Carpe Diem
    type: stdio
    cmd: npx
    args: ["-y", "carpe-diem-mcp"]
    envs: { "CARPE_API_KEY": "cdm_your_key", "CARPE_MAX_SPEND_USD": "5" }
    enabled: true
    timeout: 300

# .continue/mcpServers/carpe.yaml
name: Carpe Diem
version: 0.0.1
schema: v1
mcpServers:
  - name: Carpe Diem
    command: npx
    args: ["-y", "carpe-diem-mcp"]
    env:
      CARPE_API_KEY: ${{ secrets.CARPE_API_KEY }}
      CARPE_MAX_SPEND_USD: "5"

Other MCP clients — LM Studio (Program → Install → Edit mcp.json), Devin Desktop (formerly Windsurf: ~/.config/devin/mcp_config.json), LibreChat — take the same mcpServers block as Claude Desktop above.

Use it

Talk to your assistant normally; it picks the tools. A few prompts that work well:

• "Find the cheapest model that can summarise this file well, then summarise it." — uses carpe_quote on both surfaces before spending.
• "Generate a 16:9 hero image of a lighthouse at dawn, flat illustration, and save it in ./assets."
• "Read this paragraph aloud in French with a calm voice and save the MP3."
• "Make a 5-second clip of a paper boat on a calm lake. Quote it first." — video and music are jobs; the assistant polls carpe_video_status and saves the file.
• "Search the web for the latest Base network upgrade and summarise it with sources."
• "How much did I spend this week, on which models, and how much did the router save me?" — or run the cost_report prompt.
• "Answer this privately, inside the TEE only: …" — or run the private_inference prompt.

Complete scenarios, with code and what they cost: Use cases.

Media inputs accept an https:// URL, a data: URI or a local file path. Images under 4 MiB and audio under 8 MiB come back inline; set CARPE_OUTPUT_DIR to also save them to disk. Videos and music are always saved to a file (a finished video stays on Carpe for about ten minutes).

Configuration

Without a key or a wallet, the free tools (catalogue, prices, quotes, markets, status) still work.

Local HTTP mode

For a client that only speaks HTTP, run the server yourself:

CARPE_API_KEY=cdm_your_key npx -y carpe-diem-mcp --http --port 3333
# → http://127.0.0.1:3333/mcp  (Streamable HTTP)

It binds to 127.0.0.1. Binding anywhere else requires CARPE_MCP_AUTH_TOKEN (16+ characters, sent as Authorization: Bearer), and browser origins are refused unless listed in CARPE_MCP_ALLOWED_ORIGINS.

Troubleshooting

ChatGPT and claude.ai

ChatGPT, and Claude on the web and on mobile, only accept remote MCP servers — a public HTTPS URL, signed in with OAuth. The Carpe MCP server runs on your machine, so it cannot be added there yet. A hosted Carpe MCP server with sign-in is planned; this page will say so when it is live.

Until then:

• Claude — use Claude Desktop or Claude Code, which run the server locally (install).
• OpenAI — Codex (CLI, IDE extension, desktop app) runs it locally (install).

Coding agents

Run your coding agent on Carpe models. The agent sends its requests to Carpe instead of its usual provider, with your key. Pick a model with tool calling (capabilities.supportsFunctionCalling in /v1/models); the Models page shows live prices.

Good starting points: claude-sonnet-5-5 and claude-haiku-5-5 (Anthropic), kimi-k2-7-code, qwen3-coder-480b-a35b-instruct-turbo, deepseek-v4-pro.

Claude Code

Claude Code speaks the Anthropic format; point it at Carpe's /v1/messages:

export ANTHROPIC_BASE_URL=https://carpe-diem.xyz/api/operator
export ANTHROPIC_AUTH_TOKEN=cdm_your_key          # sent as Authorization: Bearer
export ANTHROPIC_MODEL=claude-sonnet-5-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-5-5   # background tasks
claude

• ANTHROPIC_AUTH_TOKEN is sent as Authorization: Bearer, like every other Carpe call. (ANTHROPIC_API_KEY, sent as x-api-key, is accepted on /v1/messages too.)
• Requests run on /v1, through Carpe's TEE. Claude models are listed as anonymized in the catalogue, not private: pick a private model for confidential code.
• Carpe has no /v1/messages/count_tokens; Claude Code then estimates token counts itself.
• If Claude Code reports an error about beta headers, add export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

OpenCode

Add Carpe as an OpenAI-compatible provider in opencode.json, then choose a model with /models:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "carpe": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Carpe Diem",
      "options": {
        "baseURL": "https://carpe-diem.xyz/api/operator/v1",
        "apiKey": "{env:CARPE_API_KEY}"
      },
      "models": {
        "kimi-k2-7-code": { "name": "Kimi K2.7 Code", "limit": { "context": 256000, "output": 65536 } },
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5", "limit": { "context": 1000000, "output": 128000 } }
      }
    }
  }
}

Use @ai-sdk/openai-compatible, not @ai-sdk/openai: the latter calls /v1/responses, which Carpe does not serve. For the best price on every request, use https://carpe-diem.xyz/api/operator/router as baseURL.

Aider

export OPENAI_API_BASE=https://carpe-diem.xyz/api/operator/v1
export OPENAI_API_KEY=cdm_your_key
aider --model openai/kimi-k2-7-code

Cline

In Cline's settings: API Provider → OpenAI Compatible, Base URL https://carpe-diem.xyz/api/operator/v1, your key as API Key, and a model id from the catalogue (for example kimi-k2-7-code).

Continue

# config.yaml
models:
  - name: Carpe — Kimi K2.7 Code
    provider: openai
    model: kimi-k2-7-code
    apiBase: https://carpe-diem.xyz/api/operator/v1
    apiKey: ${{ secrets.CARPE_API_KEY }}
    useResponsesApi: false

Zed

{
  "language_models": {
    "openai_compatible": {
      "carpe": {
        "api_url": "https://carpe-diem.xyz/api/operator/v1",
        "available_models": [
          { "name": "kimi-k2-7-code", "display_name": "Kimi K2.7 Code (Carpe)", "max_tokens": 256000 }
        ]
      }
    }
  }
}

Zed reads the key from the CARPE_API_KEY environment variable (the provider id in capitals, plus _API_KEY), or asks for it in the agent panel.

VS Code (Copilot)

Copilot Chat can use a custom endpoint: Chat → Manage Language Models → Custom Endpoint, or in chatLanguageModels.json:

[
  {
    "name": "Carpe Diem",
    "vendor": "customendpoint",
    "apiKey": "${input:carpeKey}",
    "apiType": "chat-completions",
    "models": [
      {
        "id": "kimi-k2-7-code",
        "name": "Kimi K2.7 Code (Carpe)",
        "url": "https://carpe-diem.xyz/api/operator/v1/chat/completions",
        "toolCalling": true,
        "maxInputTokens": 256000,
        "maxOutputTokens": 65536
      }
    ]
  }
]

Your organisation's Copilot policy may disable custom models.

Goose and llm

// ~/.config/goose/custom_providers/carpe.json — the key comes from $CARPE_API_KEY
{
  "name": "carpe",
  "engine": "openai",
  "display_name": "Carpe Diem",
  "api_key_env": "CARPE_API_KEY",
  "base_url": "https://carpe-diem.xyz/api/operator/v1/chat/completions",
  "models": [{ "name": "kimi-k2-7-code", "context_limit": 256000 }],
  "supports_streaming": true,
  "requires_auth": true
}

llm keys set carpe            # paste cdm_your_key
llm openai endpoint add https://carpe-diem.xyz/api/operator/v1 \
  -m kimi-k2-7-code --id carpe --key carpe --supports-tools
llm -m carpe "Explain this regex: ^cdm_[0-9a-f]{16,}$"

Not supported as a model provider

• Codex CLI only speaks OpenAI's Responses API (/v1/responses), which Carpe does not serve. Use Codex with the MCP server instead.
• Gemini CLI only talks to Gemini endpoints. Use it with the MCP server.
• Cursor does not let you set a custom base URL for its own models. Use it with the MCP server.

SDKs

Any OpenAI or Anthropic SDK works: change the base URL and the key, keep your code.

from openai import OpenAI
 
client = OpenAI(
    base_url="https://carpe-diem.xyz/api/operator/v1",   # or …/router for the best price
    api_key="cdm_your_key",
)
r = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Say hi in five words."}],
)
print(r.choices[0].message.content)

import OpenAI from "openai";
 
const client = new OpenAI({
  baseURL: "https://carpe-diem.xyz/api/operator/v1", // or …/router for the best price
  apiKey: process.env.CARPE_API_KEY,
});
const r = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [{ role: "user", content: "Say hi in five words." }],
});
console.log(r.choices[0].message.content);

from anthropic import Anthropic
 
client = Anthropic(
    base_url="https://carpe-diem.xyz/api/operator",   # the SDK appends /v1/messages
    auth_token="cdm_your_key",
)
r = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=200,
    messages=[{"role": "user", "content": "Say hi in five words."}],
)
print(r.content[0].text)

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic({
  baseURL: "https://carpe-diem.xyz/api/operator", // the SDK appends /v1/messages
  authToken: process.env.CARPE_API_KEY,
});
const r = await client.messages.create({
  model: "claude-haiku-5-5",
  max_tokens: 200,
  messages: [{ role: "user", content: "Say hi in five words." }],
});
console.log(r.content[0].text);

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText } from "ai";
 
const carpe = createOpenAICompatible({
  name: "carpe",
  baseURL: "https://carpe-diem.xyz/api/operator/v1",
  apiKey: process.env.CARPE_API_KEY,
  includeUsage: true,
});
const { text } = await generateText({ model: carpe("deepseek-v4-flash"), prompt: "Say hi in five words." });
console.log(text);

from langchain_openai import ChatOpenAI
 
llm = ChatOpenAI(
    model="deepseek-v4-flash",
    base_url="https://carpe-diem.xyz/api/operator/v1",
    api_key="cdm_your_key",
    use_responses_api=False,   # Carpe serves Chat Completions, not Responses
)
print(llm.invoke("Say hi in five words.").content)

# pip install llama-index-llms-openai-like
from llama_index.llms.openai_like import OpenAILike
 
llm = OpenAILike(
    model="deepseek-v4-flash",
    api_base="https://carpe-diem.xyz/api/operator/v1",
    api_key="cdm_your_key",
    is_chat_model=True,
    is_function_calling_model=True,
    context_window=128000,
)
print(llm.complete("Say hi in five words."))

from litellm import completion
 
r = completion(
    model="openai/deepseek-v4-flash",          # openai/ = any OpenAI-compatible server
    api_base="https://carpe-diem.xyz/api/operator/v1",
    api_key="cdm_your_key",
    messages=[{"role": "user", "content": "Say hi in five words."}],
)
print(r.choices[0].message.content)

curl https://carpe-diem.xyz/api/operator/v1/chat/completions \
  -H "Authorization: Bearer $CARPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"Say hi in five words."}]}'

What works the OpenAI way: streaming (stream: true, SSE), tools and tool_choice, response_format (JSON schema), images in messages (vision models), embeddings (/v1/embeddings). Images, audio, video and music have their own endpoints: see the API reference. Calls go server to server — a browser page on another site cannot call the API directly (CORS).

Chat apps & automation

Open WebUI

Admin settings → Connections → OpenAI → Add connection: URL https://carpe-diem.xyz/api/operator/v1 (or /router), your key. Verify connection lists the models. Or with environment variables:

OPENAI_API_BASE_URL=https://carpe-diem.xyz/api/operator/v1
OPENAI_API_KEY=cdm_your_key

Open WebUI connects to MCP servers over HTTP only. To give it the Carpe tools, run the local HTTP mode where Open WebUI can reach it (behind its auth token), or Open WebUI's mcpo proxy.

LibreChat

# librechat.yaml
endpoints:
  custom:
    - name: "Carpe Diem"
      apiKey: "${CARPE_API_KEY}"        # or "user_provided": each user brings a key
      baseURL: "https://carpe-diem.xyz/api/operator/v1"
      models:
        default: ["deepseek-v4-flash", "claude-sonnet-5-5"]
        fetch: true
mcpServers:
  carpe:
    type: stdio
    command: npx
    args: ["-y", "carpe-diem-mcp"]
    env:
      CARPE_API_KEY: "${CARPE_API_KEY}"
      CARPE_MAX_SPEND_USD: "5"

n8n

Create an OpenAI credential, set Base URL to https://carpe-diem.xyz/api/operator/v1 and paste your key. The OpenAI Chat Model node then lists Carpe models; leave Use Responses API off. (Make's OpenAI module has no base URL setting: use its HTTP module against the same endpoint.)

Pay per request, without an account (x402)

An autonomous agent can pay each request from its own wallet — USDC on Base, no key, no signup — with the x402 protocol.

• With the MCP server: set a wallet instead of a key. The server signs one USDC permit whose value is your budget: Carpe can never pull more than that, in total.

  "env": {
    "CARPE_X402_PRIVATE_KEY": "0x…",
    "CARPE_X402_BUDGET_USD": "2",
    "CARPE_MAX_PER_CALL_USD": "0.25"
  }

  Copy

  Use a dedicated wallet that holds only what you are willing to spend. In this mode chat is not streamed, account tools are unavailable, and cloned voices cannot be used.

• From your own code: POST /v1/x402/… without payment returns a 402 with the payment options; sign, and resend with an X-PAYMENT header. The flow, the two schemes (carpe-session, exact) and the error codes are in the API reference.

For AI agents reading this

A plain-text summary of Carpe for language models is at /llms.txt, and the full English documentation in one file at /llms-full.txt. The model catalogue (/v1/models), prices (/pricing), router markets (/router/markets) and quotes (POST /router/quote) are public and free.