Integraciones

Carpe Diem llega a tus herramientas de dos maneras:

• El servidor MCP (carpe-diem-mcp) le da a un asistente de IA — Claude Code, Claude Desktop, Cursor, Codex, VS Code, Zed… — una treintena de herramientas de Carpe: chatear con cualquier modelo, generar imágenes, video, voz y música, buscar en la web, comparar precios, consultar tu saldo. El asistente decide cuándo llamarlas; tú mantienes el control de lo que puede gastar.
• La API es compatible con OpenAI y Anthropic. Cualquier SDK, agente de programación o app de chat que te permita cambiar la URL base puede usar los modelos de Carpe directamente, sin instalar nada.

Para ambos necesitas una clave de API (o una wallet con fondos, para x402): crea una en API → Keys y luego añade créditos en API → Balance. Las claves empiezan por cdm_.

Elige tu camino

Dos superficies: /v1 y /router

Cada integración de esta página usa una de dos URL base. Aceptan la misma clave y los mismos cuerpos de solicitud; difieren en quién atiende la solicitud.

URL base completas: https://carpe-diem.xyz/api/operator/v1 y https://carpe-diem.xyz/api/operator/router. Cada respuesta te indica quién la atendió (X-Carpe-Route-Market) y cuánto costó; consulta la referencia de la API.

Servidor MCP

carpe-diem-mcp es un servidor Model Context Protocol de código abierto (MIT). Se ejecuta en tu máquina, lo inicia tu asistente con npx y se comunica con Carpe usando tu clave. Código fuente: github.com/Irdanwen/carpe-diem-mcp. Requiere Node.js 20 o posterior.

Qué le da a tu asistente

También expone tres recursos — carpe://models, carpe://pricing, carpe://markets — y tres prompts listos para usar:

• cheapest_model_for — preselecciona modelos para una tarea, cotiza cada uno en ambas superficies, ejecuta el más barato aceptable e informa del costo y del mercado.
• cost_report — saldo, gasto por modelo y por día, ahorro del router, y un aviso si el saldo cubre menos de una semana.
• private_inference — responde a una solicitud confidencial solo en /v1, con un modelo que Venice ejecuta de forma privada, y confirma que se ejecutó en el TEE.

Cada resultado indica cuánto costó y quién lo atendió (mercado, y si era un TEE). Las herramientas que existen en ambas superficies aceptan un argumento route: "carpe" (/v1, el valor por defecto) o "router" (/router).

El gasto sigue bajo tu control

El servidor calcula el precio de cada llamada de pago antes de enviarla — a partir de cotizaciones gratuitas — y la rechaza localmente, sin llamar a Carpe, cuando superaría:

• CARPE_MAX_PER_CALL_USD — por llamada (por defecto 0.50), o
• lo que queda de CARPE_MAX_SPEND_USD — por sesión (por defecto 5).

carpe_session_spend muestra el total acumulado. CARPE_READ_ONLY=1 elimina todas las herramientas que pueden gastar o modificar algo. Si una clave se filtra, carpe_revoke_this_key (con confirm: "REVOKE") la desactiva al instante. carpe_topup_link devuelve un enlace de pago para que lo abra una persona: el asistente nunca paga con tarjeta.

Las llamadas de pago solo se reintentan cuando es seguro que Carpe no las ejecutó (límite de tasa, capacidad), así que un reintento nunca factura dos veces.

Instalación

Elige tu cliente. Cada fragmento inicia el servidor con npx; sustituye cdm_your_key por tu clave. Después reinicia el cliente (o recarga sus servidores MCP) y comprueba que funciona pidiendo: "Llama a 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"

Otros clientes MCP — LM Studio (Program → Install → Edit mcp.json), Devin Desktop (antes Windsurf: ~/.config/devin/mcp_config.json), LibreChat — aceptan el mismo bloque mcpServers que Claude Desktop más arriba.

Uso

Habla con tu asistente con normalidad; él elige las herramientas. Algunos prompts que funcionan bien:

• "Encuentra el modelo más barato capaz de resumir bien este archivo y luego resúmelo." — usa carpe_quote en ambas superficies antes de gastar.
• "Genera una imagen de cabecera 16:9 de un faro al amanecer, ilustración plana, y guárdala en ./assets."
• "Lee este párrafo en voz alta en francés con una voz tranquila y guarda el MP3."
• "Haz un clip de 5 segundos de un barco de papel en un lago en calma. Cotízalo primero." — el video y la música son trabajos asíncronos; el asistente consulta carpe_video_status y guarda el archivo.
• "Busca en la web la última actualización de la red Base y resúmela con fuentes."
• "¿Cuánto gasté esta semana, en qué modelos, y cuánto me ahorró el router?" — o ejecuta el prompt cost_report.
• "Responde a esto de forma privada, solo dentro del TEE: …" — o ejecuta el prompt private_inference.

Escenarios completos, con código y lo que cuestan: Casos de uso.

Las entradas multimedia aceptan una URL https://, un URI data: o una ruta de archivo local. Las imágenes de menos de 4 MiB y el audio de menos de 8 MiB se devuelven en línea; define CARPE_OUTPUT_DIR para guardarlos también en disco. Los videos y la música siempre se guardan en un archivo (un video terminado permanece en Carpe unos diez minutos).

Configuración

Sin clave ni wallet, las herramientas gratuitas (catálogo, precios, cotizaciones, mercados, estado) siguen funcionando.

Modo HTTP local

Para un cliente que solo habla HTTP, ejecuta tú mismo el servidor:

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

Escucha en 127.0.0.1. Escuchar en cualquier otra dirección requiere CARPE_MCP_AUTH_TOKEN (16 caracteres o más, enviado como Authorization: Bearer), y los orígenes de navegador se rechazan salvo que figuren en CARPE_MCP_ALLOWED_ORIGINS.

Solución de problemas

ChatGPT y claude.ai

ChatGPT, y Claude en la web y en el móvil, solo aceptan servidores MCP remotos — una URL HTTPS pública, con inicio de sesión mediante OAuth. El servidor MCP de Carpe se ejecuta en tu máquina, así que todavía no se puede añadir ahí. Está previsto un servidor MCP de Carpe alojado con inicio de sesión; esta página lo indicará cuando esté disponible.

Mientras tanto:

• Claude — usa Claude Desktop o Claude Code, que ejecutan el servidor localmente (instalación).
• OpenAI — Codex (CLI, extensión de IDE, app de escritorio) lo ejecuta localmente (instalación).

Agentes de programación

Ejecuta tu agente de programación con modelos de Carpe. El agente envía sus solicitudes a Carpe en lugar de a su proveedor habitual, con tu clave. Elige un modelo con llamada a herramientas (capabilities.supportsFunctionCalling en /v1/models); la página Models muestra los precios en vivo.

Buenos puntos de partida: claude-sonnet-5-5 y claude-haiku-5-5 (Anthropic), kimi-k2-7-code, qwen3-coder-480b-a35b-instruct-turbo, deepseek-v4-pro.

Claude Code

Claude Code habla el formato de Anthropic; apúntalo a /v1/messages de Carpe:

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 se envía como Authorization: Bearer, como cualquier otra llamada a Carpe. (ANTHROPIC_API_KEY, enviado como x-api-key, también se acepta en /v1/messages).
• Las solicitudes se ejecutan en /v1, a través del TEE de Carpe. Los modelos Claude figuran como anonymized en el catálogo, no como private: elige un modelo private para código confidencial.
• Carpe no tiene /v1/messages/count_tokens; en ese caso Claude Code estima por sí mismo el número de tokens.
• Si Claude Code muestra un error sobre encabezados beta, añade export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

OpenCode

Añade Carpe como proveedor compatible con OpenAI en opencode.json y luego elige un modelo con /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 } }
      }
    }
  }
}

Usa @ai-sdk/openai-compatible, no @ai-sdk/openai: este último llama a /v1/responses, que Carpe no sirve. Para obtener el mejor precio en cada solicitud, usa https://carpe-diem.xyz/api/operator/router como 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

En la configuración de Cline: API Provider → OpenAI Compatible, Base URL https://carpe-diem.xyz/api/operator/v1, tu clave como API Key, y un id de modelo del catálogo (por ejemplo 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 lee la clave de la variable de entorno CARPE_API_KEY (el id del proveedor en mayúsculas, más _API_KEY), o te la pide en el panel del agente.

VS Code (Copilot)

Copilot Chat puede usar un endpoint personalizado: Chat → Manage Language Models → Custom Endpoint, o en 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
      }
    ]
  }
]

La política de Copilot de tu organización puede desactivar los modelos personalizados.

Goose y 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,}$"

No compatibles como proveedor de modelos

• Codex CLI solo habla la Responses API de OpenAI (/v1/responses), que Carpe no sirve. Usa Codex con el servidor MCP.
• Gemini CLI solo se comunica con endpoints de Gemini. Úsalo con el servidor MCP.
• Cursor no permite definir una URL base personalizada para sus propios modelos. Úsalo con el servidor MCP.

SDKs

Cualquier SDK de OpenAI o de Anthropic funciona: cambia la URL base y la clave, y conserva tu código.

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."}]}'

Lo que funciona como en OpenAI: streaming (stream: true, SSE), herramientas y tool_choice, response_format (JSON schema), imágenes en los mensajes (modelos de visión), embeddings (/v1/embeddings). Imágenes, audio, video y música tienen sus propios endpoints: consulta la referencia de la API. Las llamadas van de servidor a servidor — una página web de otro sitio no puede llamar a la API directamente desde el navegador (CORS).

Apps de chat y automatización

Open WebUI

Admin settings → Connections → OpenAI → Add connection: URL https://carpe-diem.xyz/api/operator/v1 (o /router), tu clave. Verify connection lista los modelos. O con variables de entorno:

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

Open WebUI se conecta a servidores MCP solo por HTTP. Para darle las herramientas de Carpe, ejecuta el modo HTTP local donde Open WebUI pueda alcanzarlo (detrás de su token de autenticación), o el proxy mcpo de Open WebUI.

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

Crea una credencial OpenAI, define Base URL como https://carpe-diem.xyz/api/operator/v1 y pega tu clave. El nodo OpenAI Chat Model lista entonces los modelos de Carpe; deja Use Responses API desactivado. (El módulo OpenAI de Make no tiene opción de URL base: usa su módulo HTTP contra el mismo endpoint).

Pago por solicitud, sin cuenta (x402)

Un agente autónomo puede pagar cada solicitud desde su propia wallet — USDC en Base, sin clave, sin registro — con el protocolo x402.

• Con el servidor MCP: configura una wallet en lugar de una clave. El servidor firma un único permit de USDC cuyo valor es tu presupuesto: Carpe nunca puede retirar más que eso, en total.

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

  Copiar

  Usa una wallet dedicada que contenga solo lo que estás dispuesto a gastar. En este modo el chat no se transmite en streaming, las herramientas de cuenta no están disponibles y no se pueden usar voces clonadas.

• Desde tu propio código: POST /v1/x402/… sin pago devuelve un 402 con las opciones de pago; firma y reenvía con un encabezado X-PAYMENT. El flujo, los dos esquemas (carpe-session, exact) y los códigos de error están en la referencia de la API.

Para agentes de IA que lean esto

Hay un resumen en texto plano de Carpe para modelos de lenguaje en /llms.txt, y la documentación completa en inglés en un solo archivo en /llms-full.txt. El catálogo de modelos (/v1/models), los precios (/pricing), los mercados del router (/router/markets) y las cotizaciones (POST /router/quote) son públicos y gratuitos.