Viktor

npx add-mcp 'https://api.viktor.com/mcp'

O servidor MCP Viktor permite que qualquer agente compatível com MCP delegue trabalho ao Viktor. Ele expõe os mesmos threads, execuções, resultados e arquivos da API Pública do Viktor, com duas ferramentas amigáveis para agentes que podem iniciar uma tarefa e aguardar seu resultado em uma única chamada.

• URL do servidor: https://api.viktor.com/mcp
• Transporte: HTTP Streamable
• Autenticação: chave de API do Viktor em cada requisição
• Modelo de sessão: sem estado

Conectar

1. Criar uma chave de API com escopo

Abra Configurações → Chaves de API e gere uma chave pessoal ou de equipe. Para o fluxo de trabalho ask_viktor mais simples, conceda:

• threads:create
• runs:create
• runs:read

Adicione outros escopos somente quando o cliente MCP precisar das ferramentas correspondentes. O servidor anuncia apenas as ferramentas permitidas pelos escopos atuais da chave.

2. Adicionar o servidor remoto ao seu cliente MCP

Cada cliente precisa das mesmas duas informações: a URL do servidor e um cabeçalho de autenticação. Qualquer um dos formatos de cabeçalho funciona:

• Authorization: Bearer <VIKTOR_API_KEY>
• x-api-key: <VIKTOR_API_KEY>

Claude Code

claude mcp add --transport http viktor https://api.viktor.com/mcp \
  --header "Authorization: Bearer $VIKTOR_API_KEY"

Cursor

Adicione o servidor ao ~/.cursor/mcp.json (ou ao .cursor/mcp.json do projeto):

{
  "mcpServers": {
    "viktor": {
      "url": "https://api.viktor.com/mcp",
      "headers": {
        "Authorization": "Bearer <VIKTOR_API_KEY>"
      }
    }
  }
}

Outros clientes

A maioria dos clientes MCP aceita o mesmo formato JSON mcpServers do exemplo do Cursor, ou oferece uma tela de configurações onde você insere a URL e o cabeçalho. Se o seu cliente pedir um transporte, escolha HTTP Streamable, não o transporte SSE legado.

Use o suporte a segredos ou variáveis de ambiente do seu cliente em vez de salvar uma chave ativa diretamente em um arquivo de configuração compartilhado.

3. Verificar a conexão

Chame whoami. Ela não requer escopo e retorna o tipo de chave, os escopos concedidos, o nível de limite de taxa do workspace e os limites de taxa ativos (ajustados ao nível). Se outras ferramentas estiverem ausentes, atualize os escopos da chave no painel do Viktor e atualize a lista de ferramentas do cliente.

Fluxo de trabalho recomendado

Para uma tarefa pontual, chame ask_viktor com uma mensagem:

{
  "message": "Analyze this month's revenue and summarize the biggest changes.",
  "speed": "smarter",
  "timeout_seconds": 120,
  "idempotency_key": "monthly-revenue-2026-07"
}

ask_viktor cria um thread, inicia uma execução, aguarda até timeout_seconds e retorna o resultado quando estiver pronto. Os resultados podem conter Markdown, JSON estruturado e artefatos de arquivo.

Se a espera terminar primeiro, a resposta inclui wait_timed_out: true e o run_id. Chame wait_for_run com esse ID. Não chame ask_viktor novamente, pois isso pode iniciar trabalho duplicado, a menos que a mesma chave de idempotência seja reutilizada.

Para fluxos de trabalho de longa duração ou interativos:

1. Chame create_thread para enfileirar o trabalho sem aguardar.
2. Chame wait_for_run ou get_run com o ID de execução retornado.
3. Chame send_message no mesmo thread para continuar a conversa com seu histórico.
4. Use get_file_download_url para quaisquer IDs de artefato retornados no resultado.

Referência de ferramentas

Ferramenta	O que faz	Escopos necessários
ask_viktor	Iniciar um novo thread e aguardar seu resultado	threads:create, runs:create, runs:read
create_thread	Iniciar um novo thread e enfileirar uma execução sem aguardar	threads:create, runs:create
send_message	Continuar um thread existente e enfileirar uma execução	messages:create, runs:create
wait_for_run	Aguardar uma execução terminar e retornar seu resultado	runs:read
get_run	Ler o status atual de uma execução	runs:read
get_run_result	Buscar o resultado de uma execução finalizada	runs:read
cancel_run	Solicitar o cancelamento de uma execução em andamento	runs:create
list_threads	Listar os threads da chave, do mais recente ao mais antigo	threads:read
get_thread	Obter o status de um thread	threads:read
list_messages	Listar mensagens visíveis ao usuário em um thread	messages:read
list_runs	Listar as execuções de um thread, do mais recente ao mais antigo	runs:read
run_script	Executar um script Python diretamente no sandbox e aguardar seu resultado	scripts:execute
wait_for_script_run	Aguardar uma execução de script terminar e retornar seu resultado	scripts:execute
get_script_run	Ler o status e o resultado de uma execução de script	scripts:execute
cancel_script_run	Cancelar uma execução de script enfileirada	scripts:execute
list_integrations	Listar integrações conectadas e seus módulos de SDK	integrations:read
list_integration_tools	Listar as ferramentas de SDK de uma integração com esquemas e trechos	integrations:read
get_file_download_url	Trocar um token de artefato por uma URL de curta duração	files:read
whoami	Identificar a chave, os escopos e os limites de taxa	Nenhum

Execuções de script sem agente

run_script executa um script Python diretamente no sandbox do workspace — sem turno de agente. O script é executado com a identidade do proprietário da chave e pode chamar integrações conectadas por meio do SDK do workspace. Descubra o que ele pode chamar com list_integrations e list_integration_tools; cada ferramenta vem com um trecho executável que run_script aceita como está. Arquivos de saída gravados no diretório da variável de ambiente VIKTOR_OUTPUT_DIR retornam como artefatos para get_file_download_url. Se a espera terminar antes do script concluir, a resposta inclui wait_timed_out: true — continue com wait_for_script_run, não com outro run_script. Consulte execuções de script no guia da API Pública para limites.

Saída estruturada

ask_viktor, create_thread e send_message aceitam o mesmo JSON Schema response_format da API REST. Quando fornecido, o resultado concluído inclui um valor json validado. Consulte o guia da API Pública.

Timeouts, progresso e tentativas

ask_viktor e wait_for_run realizam polling limitado no lado do servidor. Clientes que enviam um token de progresso MCP recebem notificações de progresso de melhor esforço enquanto aguardam.

Cada chamada de ferramenta é limitada pela mesma política que seu equivalente REST, ajustada ao nível do plano do workspace (planos superiores obtêm limites proporcionalmente maiores — consulte o guia da API Pública). Se uma espera expirar, chame wait_for_run novamente com o mesmo ID de execução. Use idempotency_key sempre que uma ferramenta iniciar uma execução, para que reconexões e tentativas não possam duplicar trabalho.

Erros

Falhas de autenticação são respostas HTTP simples 401 ou 403 para que clientes MCP possam reconhecer problemas de credenciais. Falhas de ferramenta são strings JSON legíveis por máquina com um error e message, e podem incluir http_status, scope ou detalhes de limite de taxa.

Correções comuns:

• Nenhuma ferramenta aparece: verifique a chave com whoami e, em seguida, conceda os escopos necessários.
• insufficient_scope: adicione o escopo nomeado à chave ou escolha uma ferramenta diferente.
• wait_timed_out: chame wait_for_run novamente com o ID de execução retornado.
• thread_busy: aguarde a execução ativa antes de enviar outra mensagem para esse thread.
• rate_limit_exceeded: aguarde o intervalo de nova tentativa antes de chamar novamente.