Scorable

Para o índice completo da documentação, veja llms.txt. Versões em Markdown das páginas de documentação estão disponíveis adicionando .md às URLs das páginas; esta página está disponível como Markdown.

Servidor MCP

Conecte Claude Code, Codex, Cursor ou qualquer cliente MCP ao servidor MCP remoto hospedado da Scorable e deixe seu agente criar e executar avaliações diretamente.

A Scorable executa um servidor MCP remoto hospedado em https://api.scorable.ai/mcp. Aponte um cliente MCP para ele com sua chave de API e seu agente terá 14 ferramentas para encontrar, executar e criar avaliações.

Use-o quando quiser que o agente avalie como parte do seu próprio loop de raciocínio: pontue um rascunho antes de mostrá-lo ao usuário, verifique uma alteração em relação a uma rubrica ou investigue por que uma pontuação regrediu. Para uso em scripts e CI, o CLI geralmente é a opção mais adequada.

Obtenha uma chave de API

Pegue uma em app.scorable.ai em API keys, ou crie uma temporária gratuita pelo terminal:

curl -s -X POST https://api.scorable.ai/create-demo-user/ | jq -r .api_key

Mantenha-a em uma variável de ambiente para que nunca caia em um arquivo de configuração que você possa commitar:

export SCORABLE_API_KEY="your-key"

Claude Code

claude mcp add --transport http scorable https://api.scorable.ai/mcp \
  --header "Authorization: Bearer $SCORABLE_API_KEY"

Isso registra o servidor para o projeto atual. Adicione --scope user para disponibilizá-lo em todos os projetos, ou --scope project para gravá-lo em .mcp.json e compartilhá-lo com sua equipe por meio do controle de versão — nesse caso, referencie a variável em vez da chave em si, para que nenhum segredo seja commitado.

Verifique se conectou:

claude mcp list

Codex

O Codex configura servidores remotos em ~/.codex/config.toml — codex mcp add é apenas para servidores stdio:

[mcp_servers.scorable]
url = "https://api.scorable.ai/mcp"
bearer_token_env_var = "SCORABLE_API_KEY"

bearer_token_env_var lê a chave do seu ambiente na inicialização e a envia como um token bearer, para que a chave fique fora do arquivo.

Cursor, VS Code e outros clientes

Qualquer coisa que fale com MCP HTTP streamable funciona. A maioria dos clientes usa este formato:

{
  "mcpServers": {
    "scorable": {
      "url": "https://api.scorable.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${SCORABLE_API_KEY}"
      }
    }
  }
}

O servidor também aceita o esquema Api-Key usado pelo restante da API Scorable, então Authorization: Api-Key <key> funciona se isso se adequar melhor ao seu cliente.

As ferramentas

Encontrando o que existe

Ferramenta	O que faz
list_judges	Juízes disponíveis para sua organização, mais recentes primeiro
get_judge	Um juiz completo, incluindo cada avaliador que ele aplica
list_evaluators	Avaliadores, incluindo os predefinidos que a Scorable oferece
get_evaluator	Um avaliador com sua rubrica e entradas obrigatórias
list_projects	Projetos, para escopo de outras chamadas

Executando avaliações

Ferramenta	O que faz
run_judge	Pontua um par de solicitação/resposta contra um juiz, por id ou nome
run_evaluator	Pontua contra um único avaliador

Criação

Ferramenta	O que faz
generate_judge	Cria um juiz a partir de uma descrição em linguagem natural do que você se importa
create_judge / update_judge	Cria ou edita um juiz a partir de uma lista explícita de avaliadores
create_evaluator / update_evaluator	Cria ou edita um único avaliador e sua rubrica

Auditoria

Ferramenta	O que faz
list_execution_logs	Execuções passadas, filtráveis por juiz, projeto, pontuação, custo, tags e data
get_execution_log	Uma execução completa, com pontuações e justificativas por avaliador

Deliberadamente não há ferramentas de exclusão. Remover um juiz ou avaliador continua sendo uma ação humana na interface ou no CLI.

Experimente

Uma vez conectado, prompts como estes se resolvem em chamadas de ferramenta:

What Scorable judges do I have?

Generate a judge that checks our support replies are concise, grounded in the
policy documents, and never promise refunds the policy does not allow.

Run that judge against this reply: "Absolutely, I've processed a full refund!"
given the policy "Refunds within 30 days, unopened items only."

Why did last night's evaluation scores drop? Check the execution logs.

O juiz gerado nesse terceiro exemplo retorna uma pontuação por avaliador com uma justificativa escrita, para que o agente possa agir sobre por que algo falhou em vez de apenas um número.

Conceitos que vale a pena conhecer

Um avaliador pontua uma qualidade de uma resposta — fidelidade ao contexto, relevância, segurança, tom ou uma rubrica personalizada — retornando uma pontuação entre 0 e 1 com uma justificativa. Um juiz é um conjunto reutilizável e nomeado de avaliadores aplicados em conjunto, e é a unidade normal de trabalho.

O servidor informa isso ao seu agente na conexão, então ele geralmente escolhe a ferramenta certa sem precisar de instruções. Veja Conceitos para o modelo completo.

Solução de problemas

401 Unauthorized — a chave está ausente, expirada ou malformada. Confirme que ela funciona contra a API REST primeiro: curl -H "Authorization: Api-Key $SCORABLE_API_KEY" https://api.scorable.ai/v1/judges/?limit=1.

404 Not Found — o endpoint está desabilitado nessa implantação. Instalações auto-hospedadas podem desativá-lo; verifique se MCP_ENABLED não está definido como false.

Uma ferramenta relata um campo ausente — alguns avaliadores exigem contexts ou expected_output. Chame get_judge e verifique o requires_contexts e o requires_expected_output de cada avaliador antes de executar.