Integrações

O Carpe Diem chega às suas ferramentas de duas formas:

• O servidor MCP (carpe-diem-mcp) dá a um assistente de IA — Claude Code, Claude Desktop, Cursor, Codex, VS Code, Zed… — cerca de trinta ferramentas Carpe: conversar com qualquer modelo, gerar imagens, vídeo, voz e música, pesquisar na web, comparar preços, consultar o saldo. O assistente decide quando as chamar; o utilizador mantém o controlo sobre o que ele pode gastar.
• A API é compatível com OpenAI e Anthropic. Qualquer SDK, agente de programação ou aplicação de chat que permita alterar o URL base pode usar diretamente os modelos do Carpe, sem nada para instalar.

Precisa de uma chave de API para ambos (ou de uma carteira com fundos, para x402): crie uma em API → Keys e depois adicione créditos em API → Balance. As chaves começam por cdm_.

Escolha o seu caminho

Duas superfícies: /v1 e /router

Cada integração abaixo usa um de dois URLs base. Aceitam a mesma chave e os mesmos corpos de pedido; diferem em quem serve o pedido.

URLs base completos: https://carpe-diem.xyz/api/operator/v1 e https://carpe-diem.xyz/api/operator/router. Cada resposta indica quem a serviu (X-Carpe-Route-Market) e quanto custou; ver a referência da API.

Servidor MCP

O carpe-diem-mcp é um servidor Model Context Protocol de código aberto (MIT). Corre na sua máquina, iniciado pelo seu assistente com npx, e comunica com o Carpe usando a sua chave. Código-fonte: github.com/Irdanwen/carpe-diem-mcp. Requer Node.js 20 ou posterior.

O que dá ao seu assistente

Expõe também três recursos — carpe://models, carpe://pricing, carpe://markets — e três prompts prontos a usar:

• cheapest_model_for — seleciona modelos para uma tarefa, cota cada um nas duas superfícies, executa o mais barato aceitável e indica o custo e o mercado.
• cost_report — saldo, gastos por modelo e por dia, poupanças do router, e um aviso se o saldo cobrir menos de uma semana.
• private_inference — responde a um pedido confidencial apenas em /v1, com um modelo que a Venice executa de forma privada, e confirma que correu no TEE.

Cada resultado indica quanto custou e quem o serviu (mercado, e se era um TEE). As ferramentas que existem nas duas superfícies aceitam um argumento route: "carpe" (/v1, por omissão) ou "router" (/router).

Os gastos ficam sob o seu controlo

O servidor calcula o preço de cada chamada paga antes de a enviar — a partir de cotações gratuitas — e recusa-a localmente, sem chamar o Carpe, quando ultrapassaria:

• CARPE_MAX_PER_CALL_USD — por chamada (por omissão 0.50), ou
• o que resta de CARPE_MAX_SPEND_USD — por sessão (por omissão 5).

carpe_session_spend mostra o total. CARPE_READ_ONLY=1 remove todas as ferramentas que podem gastar ou alterar alguma coisa. Se uma chave for comprometida, carpe_revoke_this_key (com confirm: "REVOKE") desativa-a de imediato. carpe_topup_link devolve um link de pagamento para ser aberto por um humano: o assistente nunca paga por cartão.

As chamadas pagas só são repetidas quando o Carpe certamente não as executou (limite de taxa, capacidade), pelo que uma repetição nunca é cobrada duas vezes.

Instalação

Escolha o seu cliente. Cada excerto inicia o servidor com npx; substitua cdm_your_key pela sua chave. Depois reinicie o cliente (ou recarregue os seus servidores MCP) e verifique que funciona perguntando: "Chama 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"

Outros clientes MCP — LM Studio (Program → Install → Edit mcp.json), Devin Desktop (antigo Windsurf: ~/.config/devin/mcp_config.json), LibreChat — aceitam o mesmo bloco mcpServers do Claude Desktop acima.

Utilização

Fale com o seu assistente normalmente; ele escolhe as ferramentas. Alguns prompts que funcionam bem:

• "Encontra o modelo mais barato capaz de resumir bem este ficheiro e depois resume-o." — usa carpe_quote nas duas superfícies antes de gastar.
• "Gera uma imagem de destaque 16:9 de um farol ao amanhecer, ilustração plana, e guarda-a em ./assets."
• "Lê este parágrafo em voz alta em francês com uma voz calma e guarda o MP3."
• "Faz um clip de 5 segundos de um barco de papel num lago calmo. Cota-o primeiro." — vídeo e música são tarefas assíncronas; o assistente consulta carpe_video_status e guarda o ficheiro.
• "Pesquisa na web a última atualização da rede Base e resume-a com fontes."
• "Quanto gastei esta semana, em que modelos, e quanto me poupou o router?" — ou execute o prompt cost_report.
• "Responde a isto de forma privada, apenas dentro do TEE: …" — ou execute o prompt private_inference.

Cenários completos, com código e o que custam: Casos de utilização.

As entradas multimédia aceitam um URL https://, um URI data: ou um caminho de ficheiro local. Imagens com menos de 4 MiB e áudio com menos de 8 MiB são devolvidos inline; defina CARPE_OUTPUT_DIR para os guardar também em disco. Vídeos e música são sempre guardados num ficheiro (um vídeo concluído fica no Carpe durante cerca de dez minutos).

Configuração

Sem chave nem carteira, as ferramentas gratuitas (catálogo, preços, cotações, mercados, estado) continuam a funcionar.

Modo HTTP local

Para um cliente que só fala HTTP, execute o servidor por si:

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

Fica associado a 127.0.0.1. Associá-lo a qualquer outro endereço requer CARPE_MCP_AUTH_TOKEN (16+ caracteres, enviado como Authorization: Bearer), e as origens de navegador são recusadas exceto se constarem de CARPE_MCP_ALLOWED_ORIGINS.

Resolução de problemas

ChatGPT e claude.ai

O ChatGPT, e o Claude na web e no telemóvel, só aceitam servidores MCP remotos — um URL HTTPS público, com início de sessão por OAuth. O servidor MCP do Carpe corre na sua máquina, por isso ainda não pode ser adicionado aí. Está planeado um servidor MCP do Carpe alojado, com início de sessão; esta página indicá-lo-á quando estiver disponível.

Até lá:

• Claude — use o Claude Desktop ou o Claude Code, que executam o servidor localmente (instalação).
• OpenAI — o Codex (CLI, extensão de IDE, aplicação de desktop) executa-o localmente (instalação).

Agentes de programação

Execute o seu agente de programação com modelos do Carpe. O agente envia os seus pedidos ao Carpe em vez do fornecedor habitual, com a sua chave. Escolha um modelo com chamada de ferramentas (capabilities.supportsFunctionCalling em /v1/models); a página Models mostra os preços em tempo real.

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

Claude Code

O Claude Code fala o formato Anthropic; aponte-o para o /v1/messages do 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 é enviado como Authorization: Bearer, como qualquer outra chamada ao Carpe. (ANTHROPIC_API_KEY, enviado como x-api-key, também é aceite em /v1/messages.)
• Os pedidos correm em /v1, através do TEE do Carpe. Os modelos Claude estão listados como anonymized no catálogo, não private: escolha um modelo private para código confidencial.
• O Carpe não tem /v1/messages/count_tokens; o Claude Code estima então ele próprio a contagem de tokens.
• Se o Claude Code reportar um erro sobre cabeçalhos beta, adicione export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

OpenCode

Adicione o Carpe como fornecedor compatível com OpenAI em opencode.json e depois escolha um modelo com /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, não @ai-sdk/openai: este último chama /v1/responses, que o Carpe não serve. Para obter o melhor preço em cada pedido, use 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

Nas definições do Cline: API Provider → OpenAI Compatible, Base URL https://carpe-diem.xyz/api/operator/v1, a sua chave como API Key, e um id de modelo do catálogo (por exemplo 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 }
        ]
      }
    }
  }
}

O Zed lê a chave da variável de ambiente CARPE_API_KEY (o id do fornecedor em maiúsculas, mais _API_KEY), ou pede-a no painel do agente.

VS Code (Copilot)

O Copilot Chat pode usar um endpoint personalizado: Chat → Manage Language Models → Custom Endpoint, ou em 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
      }
    ]
  }
]

A política do Copilot da sua organização pode desativar os modelos personalizados.

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

Não suportados como fornecedor de modelos

• O Codex CLI só fala a Responses API da OpenAI (/v1/responses), que o Carpe não serve. Use o Codex com o servidor MCP.
• O Gemini CLI só comunica com endpoints Gemini. Use-o com o servidor MCP.
• O Cursor não permite definir um URL base personalizado para os seus próprios modelos. Use-o com o servidor MCP.

SDKs

Qualquer SDK da OpenAI ou da Anthropic funciona: altere o URL base e a chave, mantenha o seu 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."}]}'

O que funciona à maneira da OpenAI: streaming (stream: true, SSE), ferramentas e tool_choice, response_format (JSON schema), imagens nas mensagens (modelos de visão), embeddings (/v1/embeddings). Imagens, áudio, vídeo e música têm os seus próprios endpoints: ver a referência da API. As chamadas são de servidor para servidor — uma página de navegador noutro site não pode chamar a API diretamente (CORS).

Aplicações de chat e automação

Open WebUI

Admin settings → Connections → OpenAI → Add connection: URL https://carpe-diem.xyz/api/operator/v1 (ou /router), a sua chave. Verify connection lista os modelos. Ou com variáveis de ambiente:

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

O Open WebUI liga-se a servidores MCP apenas por HTTP. Para lhe dar as ferramentas Carpe, execute o modo HTTP local num local acessível ao Open WebUI (protegido pelo seu token de autenticação), ou o proxy mcpo do 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

Crie uma credencial OpenAI, defina Base URL como https://carpe-diem.xyz/api/operator/v1 e cole a sua chave. O nó OpenAI Chat Model passa então a listar os modelos do Carpe; deixe Use Responses API desativado. (O módulo OpenAI do Make não tem definição de URL base: use o seu módulo HTTP com o mesmo endpoint.)

Pagar por pedido, sem conta (x402)

Um agente autónomo pode pagar cada pedido a partir da sua própria carteira — USDC na Base, sem chave, sem registo — com o protocolo x402.

• Com o servidor MCP: defina uma carteira em vez de uma chave. O servidor assina um único permit USDC cujo valor é o seu orçamento: o Carpe nunca pode retirar mais do que isso, no total.

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

  Copiar

  Use uma carteira dedicada que contenha apenas o que está disposto a gastar. Neste modo o chat não é transmitido em streaming, as ferramentas de conta não estão disponíveis e não é possível usar vozes clonadas.

• A partir do seu próprio código: POST /v1/x402/… sem pagamento devolve um 402 com as opções de pagamento; assine e reenvie com um cabeçalho X-PAYMENT. O fluxo, os dois esquemas (carpe-session, exact) e os códigos de erro estão na referência da API.

Para agentes de IA que leiam isto

Um resumo em texto simples do Carpe para modelos de linguagem está em /llms.txt, e a documentação completa em inglês num único ficheiro em /llms-full.txt. O catálogo de modelos (/v1/models), os preços (/pricing), os mercados do router (/router/markets) e as cotações (POST /router/quote) são públicos e gratuitos.