Servidor MCP

O servidor MCP da Dcision em https://api.dcision.io/mcp — autenticação, as catorze ferramentas com entradas e saídas, erros e configuração para Claude Code, Cursor, VS Code, Claude Desktop, Codex, Gemini CLI e curl.

Endpoint    https://api.dcision.io/mcp
Transport   Streamable HTTP (stateless, JSON responses)
Auth        Authorization: Bearer dcs_live_… | dcs_test_…

O servidor Model Context Protocol permite que agentes de IA e assistentes de código usem a Dcision: listar as suas decisões, ler o contrato delas, checar e rodar estados, ler execuções, navegar pelos templates e validar decision schemas. Ele faz parte da API da Dcision — as mesmas chaves, os mesmos limites e a mesma cobrança da API REST.

Para uma configuração passo a passo no Claude Code, com a skill da Dcision, veja Use a Dcision no Claude Code.

Autenticação

Envie uma API key do workspace como token Bearer em toda requisição. O servidor não mantém sessão nem guarda credenciais: cada requisição é autenticada por si só, e as ferramentas agem no workspace da chave.

  • Sem chave, com uma chave malformada ou com uma chave revogada → HTTP 401, com um header WWW-Authenticate: Bearer e uma mensagem que diz onde criar uma chave.
  • Só API keys são aceitas — nunca uma sessão do app.
  • Prefira uma chave dcs_test_… enquanto experimenta: as execuções são reais e contam como uso, mas os destinos entregam com livemode: false.

Limites e cobrança

Toda requisiçãoConta na janela de rate limit de leitura, compartilhada com GET /v1/me, GET /v1/decisions e GET /v1/executions. Leituras não são cobradas.
run_decisionConta também na janela de decisões, compartilhada com POST /v1/decisions/{slug}. Cobrada como uma chamada à API, com a mesma cota.
RequisiçõesSó POST /mcp. GET /mcp e DELETE /mcp respondem 405: não há sessões nem stream de server-sent events.
Tamanho do bodyAté 1 MB, para que validate_schema, create_decision e update_decision aceitem schemas grandes (os prompts de agente vão até 32.000 caracteres). O state de check_state e run_decision continua limitado a 128 KB (INVALID_STATE). Bodies maiores respondem 413 PAYLOAD_TOO_LARGE.

Ferramentas

Toda ferramenta devolve o resultado como JSON — como texto no content do resultado e como structuredContent. As leituras são anotadas com readOnlyHint: true. run_decision, create_decision, update_decision e deploy_decision são anotadas como nem somente leitura nem idempotentes, e deploy_decision também como destrutiva (ela muda o que roda em produção), para que os clientes possam perguntar antes de chamá-las.

FerramentaSomente leituraArgumentosDevolve
get_accountSim—O workspace da chave, a chave, o plano e o uso deste período — o body de GET /v1/me.
list_decisionsSim—As decisões do workspace com slug, nome, status e versão ativa — o body de GET /v1/decisions.
get_decisionSimslugO contrato de uma decisão — state schema, perguntas com as opções, ações, ação de fallback e um estado de exemplo — o body de GET /v1/decisions/{slug}.
check_stateSimslug, state{ "valid": true }, ou { "valid": false, "message" } com o motivo pelo qual uma execução falharia com 422 INVALID_STATE. Confere o state schema da versão ativa e o limite de tokens do próprio estado; nada roda. Uma execução ainda pode responder 422 quando o estado mais a pergunta mais longa passam do orçamento de tokens do engine.
run_decisionNão — cobradaslug, state, include_probabilities (boolean) opcionalA resposta da decisão, como POST /v1/decisions/{slug} a devolve.
list_executionsSimopcionais decision (slug), status (success ou error), limit (1–100, padrão 20), cursorExecuções recentes, nunca as entradas — o body de GET /v1/executions.
list_templatesSim—{ "data": [...] } com id, name, description, category e patterns de cada template.
get_templateSimidO resumo do template mais o decision schema completo dele em schema e um sample_state.
validate_schemaSimschema (object){ "valid": true, "schema" } com o schema normalizado — other adicionado, padrões preenchidos — ou { "valid": false, "issues": [{ "path", "message" }] }. As mesmas regras do editor e da API.
create_decisionNãoname (1–80), schema (object), opcionais slug, description (≤ 500)Cria uma decisão em rascunho. Devolve a decisão com o slug e status: "draft". Conta para o limite de decisões do plano (PLAN_LIMIT_REACHED).
update_decisionNãoslug, opcionais schema, name, descriptionSubstitui o schema do rascunho e/ou renomeia a decisão. O que roda não muda até deploy_decision.
deploy_decisionNão — destrutivaslugPublica o rascunho como uma nova versão: as próximas execuções o usam.
list_workspacesSimopcionais external_id, limit (1–100), cursorModo parceiro: os seus sub-workspaces com limites e uso — o body de GET /v1/workspaces.
upsert_workspaceNãoexternal_id, name, opcionais seed_decisions (slugs), deploy (boolean)Modo parceiro: cria o sub-workspace de um cliente (ou o renomeia), opcionalmente copiando decisões publicadas para ele.

Cada ferramenta publica o schema de entrada exato em tools/list: leia-o ali quando construir o seu próprio cliente.

Agir num sub-workspace

Os parceiros enviam o header Dcision-Workspace: ext:<external_id> (ou o id do sub-workspace) com a própria API key: toda ferramenta então lê, roda, cria e publica no sub-workspace desse cliente, e o rate limit continua sendo o do seu workspace. Um sub-workspace de outro workspace responde 404 (erro JSON-RPC -32004).

claude mcp add --transport http dcision-acme https://api.dcision.io/mcp \
  --header "Authorization: Bearer $DCISION_API_KEY" --header "Dcision-Workspace: ext:acme"

Rodar decisões

O fluxo usual, que a skill da Dcision ensina aos agentes:

  1. list_decisions — escolha uma decisão cujo status seja deployed.
  2. get_decision — leia state_schema e parta de example_state.
  3. check_state — corrija o estado até ele passar; não custa nada.
  4. run_decision — rode uma vez e então aja com base em action.

run_decision envia o estado como a API faz: um objeto, uma string ou um array, conforme o tipo de estado da decisão. Ela não tem chave de idempotência: toda chamada que chega ao engine roda e é cobrada. Se uma chamada falhar na rede, procure a execução com list_executions antes de tentar de novo. Para retries seguros por construção, chame a API REST com um Idempotency-Key.

Escrever decisões

Um agente consegue montar uma decisão de ponta a ponta:

  1. get_template — parta de um template quando algum servir.
  2. validate_schema — corrija o schema até ele não ter problemas.
  3. create_decision — cria a decisão como rascunho.
  4. update_decision — itere sobre o rascunho; nada muda em produção.
  5. deploy_decision — publique. Pergunte ao usuário antes deste passo.

As escritas são feitas em nome da pessoa que criou a API key; uma chave sem autor é recusada (FORBIDDEN). Excluir ou desativar uma decisão, o time, os segredos de destinos e a cobrança continuam no app.

Erros

OndeO que você recebe
Erro HTTP + JSON-RPC401 sem uma API key válida (com WWW-Authenticate: Bearer), 429 quando a janela de leitura acabou, 405 para qualquer método que não seja POST, 406 sem Accept: application/json, text/event-stream, 400 para um batch JSON-RPC (envie uma mensagem por requisição). O body é um error JSON-RPC cujo message diz o que fazer. Um body que nem é JSON recebe o objeto de erro 400 INVALID_REQUEST da própria API.
Resultado da ferramentaisError: true e { "error": { "code", "message", "details" } } como texto, para tudo o que a API responderia com um erro — DECISION_NOT_FOUND, DECISION_NOT_DEPLOYED, INVALID_STATE, CREDITS_EXHAUSTED, SPEND_CAP_REACHED, QUOTA_EXCEEDED, RATE_LIMITED em run_decision, erros de engine — e também para uma ferramenta desconhecida (NOT_FOUND) ou argumentos inválidos (INVALID_REQUEST, com cada problema em details). Veja Erros.

Um agente deve ler o message do erro — ele diz o que corrigir — e não repetir um 4xx sem mudanças.

Claude Code

claude mcp add --transport http dcision https://api.dcision.io/mcp \
  --header "Authorization: Bearer $DCISION_API_KEY" \
  --scope user

Tire o --scope user para adicioná-lo só ao projeto atual, ou faça commit de um .mcp.json que lê a chave do ambiente de cada pessoa:

.mcp.json
{
  "mcpServers": {
    "dcision": {
      "type": "http",
      "url": "https://api.dcision.io/mcp",
      "headers": { "Authorization": "Bearer ${DCISION_API_KEY}" }
    }
  }
}

Mais em Use a Dcision no Claude Code.

Outros clientes

Qualquer cliente MCP que suporte servidores remotos via Streamable HTTP com um header personalizado consegue se conectar.

{
  "mcpServers": {
    "dcision": {
      "url": "https://api.dcision.io/mcp",
      "headers": { "Authorization": "Bearer ${env:DCISION_API_KEY}" }
    }
  }
}
  • Cursor — ~/.cursor/mcp.json para todos os projetos, ou .cursor/mcp.json num repositório.
  • VS Code — .vscode/mcp.json; o VS Code pede a chave uma vez e a guarda com segurança.
  • Claude Desktop — Settings → Developer → Edit Config (claude_desktop_config.json). O Claude Desktop se conecta a servidores remotos por meio do mcp-remote, uma ponte da comunidade que precisa de Node.js; o header é passado por uma variável de ambiente para que o espaço depois de Bearer sobreviva em todas as plataformas. Reinicie o Claude Desktop depois de editar.
  • Codex — ~/.codex/config.toml, com DCISION_API_KEY exportada onde o Codex roda.
  • Gemini CLI — ~/.gemini/settings.json ou .gemini/settings.json num projeto.

ChatGPT e claude.ai

Os conectores do ChatGPT e do claude.ai fazem login com OAuth, que o servidor MCP da Dcision ainda não oferece: ele só aceita uma API key num header. Use um dos clientes acima, ou a API REST.

Chame o servidor com curl

O servidor fala JSON-RPC 2.0 puro sobre HTTP e é stateless — nenhum handshake initialize é necessário. Envie Content-Type: application/json e Accept: application/json, text/event-stream:

curl -s https://api.dcision.io/mcp \
  -H "Authorization: Bearer $DCISION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Chame uma ferramenta com tools/call, o name e os arguments dela:

curl -s https://api.dcision.io/mcp \
  -H "Authorization: Bearer $DCISION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": { "name": "get_decision", "arguments": { "slug": "lead-qualification" } }
  }' | jq '.result.structuredContent'

A resposta é uma resposta JSON-RPC: result.content[0].text traz o JSON da ferramenta como texto e result.structuredContent o mesmo valor como objeto (resumida):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "{\"slug\": \"lead-qualification\", \"status\": \"deployed\", \"version\": 3}" }],
    "structuredContent": { "slug": "lead-qualification", "status": "deployed", "version": 3 }
  }
}

É assim também que a skill da Dcision chega a validate_schema, check_state e aos templates quando nenhum cliente MCP está configurado.

Segurança

  • O servidor age só no workspace da chave; uma chave não alcança as decisões de outro workspace.
  • As ferramentas nunca devolvem as entradas de execuções anteriores, segredos, a configuração dos destinos (URLs, headers) nem o schema completo de uma decisão — só o contrato da versão ativa. Os resultados de run_decision e list_executions incluem as entradas destinations de cada execução, que podem trazer valores mapeados do estado (params de funções, respostas de LLM ou de agentes): trate-os como qualquer saída de decisão.
  • Trate uma chave usada por um agente como qualquer segredo de produção: mantenha-a no ambiente, use uma chave de teste enquanto experimenta e revogue-a em API Keys se ela vazar.

Nesta página