Intégrations

Carpe Diem rejoint vos outils de deux façons :

• Le serveur MCP (carpe-diem-mcp) donne à un assistant IA — Claude Code, Claude Desktop, Cursor, Codex, VS Code, Zed… — une trentaine d'outils Carpe : discuter avec n'importe quel modèle, générer images, vidéo, voix et musique, chercher sur le web, comparer les prix, consulter votre solde. L'assistant décide quand les appeler ; vous gardez la main sur ce qu'il peut dépenser.
• L'API est compatible OpenAI et Anthropic. Tout SDK, agent de code ou application de chat qui permet de changer l'URL de base peut utiliser directement les modèles Carpe, sans rien installer.

Dans les deux cas, il vous faut une clé API (ou un wallet approvisionné, pour x402) : créez-en une dans API → Keys, puis ajoutez des crédits dans API → Balance. Les clés commencent par cdm_.

Choisir votre voie

Deux surfaces : /v1 et /router

Chaque intégration ci-dessous utilise l'une de deux URL de base. Elles acceptent la même clé et les mêmes corps de requête ; elles diffèrent par qui sert la requête.

URL de base complètes : https://carpe-diem.xyz/api/operator/v1 et https://carpe-diem.xyz/api/operator/router. Chaque réponse indique qui l'a servie (X-Carpe-Route-Market) et ce qu'elle a coûté ; voir la référence de l'API.

Serveur MCP

carpe-diem-mcp est un serveur Model Context Protocol open source (MIT). Il tourne sur votre machine, lancé par votre assistant avec npx, et communique avec Carpe grâce à votre clé. Code source : github.com/Irdanwen/carpe-diem-mcp. Nécessite Node.js 20 ou plus récent.

Ce qu'il apporte à votre assistant

Il expose aussi trois ressources — carpe://models, carpe://pricing, carpe://markets — et trois prompts prêts à l'emploi :

• cheapest_model_for — présélectionne des modèles pour une tâche, obtient un devis pour chacun sur les deux surfaces, exécute le moins cher qui convient, puis indique le coût et le marché.
• cost_report — solde, dépenses par modèle et par jour, économies du router, et une alerte si le solde couvre moins d'une semaine.
• private_inference — répond à une demande confidentielle sur /v1 uniquement, avec un modèle que Venice exécute de façon privée, et confirme qu'elle a tourné dans le TEE.

Chaque résultat indique ce qu'il a coûté et qui l'a servi (le marché, et s'il s'agissait d'un TEE). Les outils disponibles sur les deux surfaces acceptent un argument route : "carpe" (/v1, par défaut) ou "router" (/router).

Vous gardez la main sur les dépenses

Le serveur chiffre chaque appel payant avant de l'envoyer — à partir de devis gratuits — et le refuse localement, sans appeler Carpe, s'il dépasserait :

• CARPE_MAX_PER_CALL_USD — par appel (0.50 par défaut), ou
• ce qu'il reste de CARPE_MAX_SPEND_USD — par session (5 par défaut).

carpe_session_spend affiche le total. CARPE_READ_ONLY=1 retire tous les outils capables de dépenser ou de modifier quoi que ce soit. Si une clé fuite, carpe_revoke_this_key (avec confirm: "REVOKE") la désactive immédiatement. carpe_topup_link renvoie un lien de paiement qu'un humain doit ouvrir : l'assistant ne paie jamais par carte.

Les appels payants ne sont réessayés que lorsque Carpe ne les a certainement pas exécutés (limite de débit, capacité), si bien qu'une nouvelle tentative n'est jamais facturée deux fois.

Installation

Choisissez votre client. Chaque extrait lance le serveur avec npx ; remplacez cdm_your_key par votre clé. Redémarrez ensuite le client (ou rechargez ses serveurs MCP) et vérifiez que tout fonctionne en demandant : « Appelle 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"

Les autres clients MCP — LM Studio (Program → Install → Edit mcp.json), Devin Desktop (anciennement Windsurf : ~/.config/devin/mcp_config.json), LibreChat — acceptent le même bloc mcpServers que Claude Desktop ci-dessus.

Utilisation

Parlez normalement à votre assistant ; il choisit les outils. Quelques prompts qui fonctionnent bien :

• « Trouve le modèle le moins cher capable de bien résumer ce fichier, puis résume-le. » — utilise carpe_quote sur les deux surfaces avant de dépenser.
• « Génère une image d'en-tête 16:9 d'un phare à l'aube, en illustration flat, et enregistre-la dans ./assets. »
• « Lis ce paragraphe à voix haute en français avec une voix calme et enregistre le MP3. »
• « Fais un clip de 5 secondes d'un bateau en papier sur un lac calme. Donne-moi d'abord un devis. » — la vidéo et la musique sont des tâches asynchrones ; l'assistant interroge carpe_video_status et enregistre le fichier.
• « Cherche sur le web la dernière mise à jour du réseau Base et résume-la avec les sources. »
• « Combien ai-je dépensé cette semaine, sur quels modèles, et combien le router m'a-t-il fait économiser ? » — ou lancez le prompt cost_report.
• « Réponds à ceci de façon privée, uniquement dans le TEE : … » — ou lancez le prompt private_inference.

Des scénarios complets, avec le code et leur coût : Cas d'usage.

Les entrées média acceptent une URL https://, une URI data: ou un chemin de fichier local. Les images de moins de 4 Mio et l'audio de moins de 8 Mio sont renvoyés directement dans la réponse ; définissez CARPE_OUTPUT_DIR pour les enregistrer aussi sur disque. Les vidéos et la musique sont toujours enregistrées dans un fichier (une vidéo terminée reste sur Carpe une dizaine de minutes).

Configuration

Sans clé ni wallet, les outils gratuits (catalogue, prix, devis, marchés, statut) fonctionnent quand même.

Mode HTTP local

Pour un client qui ne parle que HTTP, lancez le serveur vous-même :

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

Il écoute sur 127.0.0.1. Écouter sur une autre adresse exige CARPE_MCP_AUTH_TOKEN (16 caractères ou plus, envoyé en Authorization: Bearer), et les origines navigateur sont refusées sauf si elles figurent dans CARPE_MCP_ALLOWED_ORIGINS.

Dépannage

ChatGPT et claude.ai

ChatGPT, ainsi que Claude sur le web et sur mobile, n'acceptent que des serveurs MCP distants — une URL HTTPS publique, avec connexion OAuth. Le serveur MCP Carpe tourne sur votre machine : il ne peut donc pas encore y être ajouté. Un serveur MCP Carpe hébergé, avec connexion, est prévu ; cette page l'annoncera dès qu'il sera en ligne.

D'ici là :

• Claude — utilisez Claude Desktop ou Claude Code, qui lancent le serveur en local (installation).
• OpenAI — Codex (CLI, extension IDE, application de bureau) le lance en local (installation).

Agents de code

Faites tourner votre agent de code sur les modèles Carpe. L'agent envoie ses requêtes à Carpe au lieu de son fournisseur habituel, avec votre clé. Choisissez un modèle qui gère l'appel d'outils (capabilities.supportsFunctionCalling dans /v1/models) ; la page Models affiche les prix en direct.

Bons points de départ : claude-sonnet-5-5 et claude-haiku-5-5 (Anthropic), kimi-k2-7-code, qwen3-coder-480b-a35b-instruct-turbo, deepseek-v4-pro.

Claude Code

Claude Code parle le format Anthropic ; pointez-le vers /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 est envoyé en Authorization: Bearer, comme tout autre appel à Carpe. (ANTHROPIC_API_KEY, envoyé en x-api-key, est aussi accepté sur /v1/messages.)
• Les requêtes passent par /v1, via le TEE de Carpe. Les modèles Claude sont listés anonymized dans le catalogue, pas private : choisissez un modèle private pour du code confidentiel.
• Carpe n'a pas de /v1/messages/count_tokens ; Claude Code estime alors lui-même le nombre de tokens.
• Si Claude Code signale une erreur liée aux en-têtes beta, ajoutez export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

OpenCode

Ajoutez Carpe comme fournisseur compatible OpenAI dans opencode.json, puis choisissez un modèle avec /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 } }
      }
    }
  }
}

Utilisez @ai-sdk/openai-compatible, pas @ai-sdk/openai : ce dernier appelle /v1/responses, que Carpe ne sert pas. Pour obtenir le meilleur prix à chaque requête, utilisez https://carpe-diem.xyz/api/operator/router comme 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

Dans les réglages de Cline : API Provider → OpenAI Compatible, Base URL https://carpe-diem.xyz/api/operator/v1, votre clé comme API Key, et un identifiant de modèle du catalogue (par exemple 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 lit la clé dans la variable d'environnement CARPE_API_KEY (l'identifiant du fournisseur en majuscules, suivi de _API_KEY), ou la demande dans le panneau de l'agent.

VS Code (Copilot)

Copilot Chat peut utiliser un endpoint personnalisé : Chat → Manage Language Models → Custom Endpoint, ou dans 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 politique Copilot de votre organisation peut désactiver les modèles personnalisés.

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

Non pris en charge comme fournisseur de modèles

• Codex CLI ne parle que la Responses API d'OpenAI (/v1/responses), que Carpe ne sert pas. Utilisez plutôt Codex avec le serveur MCP.
• Gemini CLI ne dialogue qu'avec des endpoints Gemini. Utilisez-le avec le serveur MCP.
• Cursor ne permet pas de définir une URL de base personnalisée pour ses propres modèles. Utilisez-le avec le serveur MCP.

SDK

Tout SDK OpenAI ou Anthropic fonctionne : changez l'URL de base et la clé, gardez votre 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."}]}'

Ce qui fonctionne à la manière d'OpenAI : le streaming (stream: true, SSE), les outils et tool_choice, response_format (JSON schema), les images dans les messages (modèles de vision), les embeddings (/v1/embeddings). Les images, l'audio, la vidéo et la musique ont leurs propres endpoints : voir la référence de l'API. Les appels se font de serveur à serveur — une page web hébergée sur un autre site ne peut pas appeler l'API directement (CORS).

Applications de chat et automatisation

Open WebUI

Admin settings → Connections → OpenAI → Add connection : URL https://carpe-diem.xyz/api/operator/v1 (ou /router), votre clé. Verify connection liste les modèles. Ou avec des variables d'environnement :

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

Open WebUI ne se connecte aux serveurs MCP qu'en HTTP. Pour lui donner les outils Carpe, lancez le mode HTTP local là où Open WebUI peut l'atteindre (derrière son jeton d'authentification), ou utilisez le proxy mcpo d'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

Créez un identifiant OpenAI, réglez Base URL sur https://carpe-diem.xyz/api/operator/v1 et collez votre clé. Le nœud OpenAI Chat Model liste alors les modèles Carpe ; laissez Use Responses API désactivé. (Le module OpenAI de Make n'a pas de réglage d'URL de base : utilisez son module HTTP sur le même endpoint.)

Payer à la requête, sans compte (x402)

Un agent autonome peut payer chaque requête depuis son propre wallet — en USDC sur Base, sans clé ni inscription — grâce au protocole x402.

• Avec le serveur MCP : configurez un wallet au lieu d'une clé. Le serveur signe un seul permit USDC dont la valeur est votre budget : Carpe ne peut jamais prélever plus que cela, au total.

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

  Copier

  Utilisez un wallet dédié qui ne contient que ce que vous êtes prêt à dépenser. Dans ce mode, le chat n'est pas diffusé en streaming, les outils de compte sont indisponibles et les voix clonées ne peuvent pas être utilisées.

• Depuis votre propre code : POST /v1/x402/… sans paiement renvoie un 402 avec les options de paiement ; signez, puis renvoyez la requête avec un en-tête X-PAYMENT. Le flux, les deux schémas (carpe-session, exact) et les codes d'erreur sont dans la référence de l'API.

Pour les agents IA qui lisent ceci

Un résumé de Carpe en texte brut destiné aux modèles de langage se trouve sur /llms.txt, et la documentation complète en anglais en un seul fichier sur /llms-full.txt. Le catalogue des modèles (/v1/models), les prix (/pricing), les marchés du router (/router/markets) et les devis (POST /router/quote) sont publics et gratuits.