Viktor

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

El servidor MCP de Viktor permite que cualquier agente compatible con MCP delegue trabajo a Viktor. Expone los mismos hilos, ejecuciones, resultados y archivos que la API pública de Viktor, con dos herramientas amigables para agentes que pueden iniciar una tarea y esperar su resultado en una sola llamada.

• URL del servidor: https://api.viktor.com/mcp
• Transporte: HTTP transmisible
• Autenticación: Clave API de Viktor en cada solicitud
• Modelo de sesión: Sin estado

Conectar

1. Crear una clave API con alcance

Abre Configuración → Claves API y genera una clave personal o de equipo. Para el flujo de trabajo ask_viktor más simple, otorga:

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

Agrega otros alcances solo cuando el cliente MCP necesite las herramientas correspondientes. El servidor anuncia únicamente las herramientas permitidas por los alcances actuales de la clave.

2. Agregar el servidor remoto a tu cliente MCP

Cada cliente necesita la misma información: la URL del servidor y un encabezado de autenticación. Cualquier estilo de encabezado 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

Agrega el servidor a ~/.cursor/mcp.json (o al .cursor/mcp.json del proyecto):

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

Otros clientes

La mayoría de los clientes MCP aceptan la misma forma JSON mcpServers que el ejemplo de Cursor, u ofrecen una pantalla de configuración donde ingresas la URL y el encabezado. Si tu cliente solicita un transporte, elige HTTP transmisible, no el transporte SSE heredado.

Usa el soporte de secretos o variables de entorno de tu cliente en lugar de guardar una clave activa directamente en un archivo de configuración compartido.

3. Verificar la conexión

Llama a whoami. No requiere alcance y devuelve el tipo de clave, los alcances otorgados, el nivel de límite de velocidad del espacio de trabajo y los límites de velocidad activos (escalados por nivel). Si faltan otras herramientas, actualiza los alcances de la clave en el panel de Viktor y actualiza la lista de herramientas del cliente.

Flujo de trabajo recomendado

Para una tarea puntual, llama a ask_viktor con un mensaje:

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

ask_viktor crea un hilo, inicia una ejecución, espera hasta timeout_seconds y devuelve el resultado cuando está listo. Los resultados pueden contener Markdown, JSON estructurado y archivos adjuntos.

Si la espera termina primero, la respuesta incluye wait_timed_out: true y el run_id. Llama a wait_for_run con ese ID. No llames a ask_viktor nuevamente, porque eso puede iniciar trabajo duplicado a menos que se reutilice la misma clave de idempotencia.

Para flujos de trabajo de larga duración o interactivos:

1. Llama a create_thread para poner trabajo en cola sin esperar.
2. Llama a wait_for_run o get_run con el ID de ejecución devuelto.
3. Llama a send_message en el mismo hilo para continuar la conversación con su historial.
4. Usa get_file_download_url para cualquier ID de archivo adjunto devuelto en el resultado.

Referencia de herramientas

Herramienta	Qué hace	Alcances requeridos
ask_viktor	Iniciar un nuevo hilo y esperar su resultado	threads:create, runs:create, runs:read
create_thread	Iniciar un nuevo hilo y poner una ejecución en cola sin esperar	threads:create, runs:create
send_message	Continuar un hilo existente y poner una ejecución en cola	messages:create, runs:create
wait_for_run	Esperar a que una ejecución termine y devolver su resultado	runs:read
get_run	Leer el estado actual de una ejecución	runs:read
get_run_result	Obtener el resultado de una ejecución terminal	runs:read
cancel_run	Solicitar la cancelación de una ejecución en curso	runs:create
list_threads	Listar los hilos de la clave, más recientes primero	threads:read
get_thread	Obtener el estado de un hilo	threads:read
list_messages	Listar mensajes visibles para el usuario en un hilo	messages:read
list_runs	Listar las ejecuciones de un hilo, más recientes primero	runs:read
run_script	Ejecutar un script de Python directamente en el sandbox y esperar su resultado	scripts:execute
wait_for_script_run	Esperar a que una ejecución de script termine y devolver su resultado	scripts:execute
get_script_run	Leer el estado y resultado de una ejecución de script	scripts:execute
cancel_script_run	Cancelar una ejecución de script en cola	scripts:execute
list_integrations	Listar integraciones conectadas y sus módulos SDK	integrations:read
list_integration_tools	Listar las herramientas SDK de una integración con esquemas y fragmentos	integrations:read
get_file_download_url	Intercambiar un token de archivo adjunto por una URL de corta duración	files:read
whoami	Identificar la clave, alcances y límites de velocidad	Ninguno

Ejecuciones de script sin agente

run_script ejecuta un script de Python directamente en el sandbox del espacio de trabajo, sin turno de agente. El script se ejecuta con la identidad del propietario de la clave y puede llamar a integraciones conectadas a través del SDK del espacio de trabajo. Descubre qué puede llamar con list_integrations y list_integration_tools; cada herramienta incluye un fragmento ejecutable que run_script acepta tal cual. Los archivos de salida escritos en el directorio de la variable de entorno VIKTOR_OUTPUT_DIR se devuelven como archivos adjuntos para get_file_download_url. Si la espera termina antes de que el script finalice, la respuesta incluye wait_timed_out: true — continúa con wait_for_script_run, no con otro run_script. Consulta ejecuciones de script en la guía de la API pública para conocer los límites.

Salida estructurada

ask_viktor, create_thread y send_message aceptan el mismo response_format JSON Schema que la API REST. Cuando se proporciona, el resultado completado incluye un valor json validado. Consulta la guía de la API pública.

Tiempos de espera, progreso y reintentos

ask_viktor y wait_for_run realizan sondeos limitados del lado del servidor. Los clientes que envían un token de progreso MCP reciben notificaciones de progreso de mejor esfuerzo mientras esperan.

Cada llamada a herramienta está limitada por la misma política que su equivalente REST, escalada al nivel del plan del espacio de trabajo (los planes superiores obtienen límites proporcionalmente más altos — consulta la guía de la API pública). Si una espera agota el tiempo, llama a wait_for_run nuevamente con el mismo ID de ejecución. Usa idempotency_key siempre que una herramienta inicie una ejecución para que las reconexiones y reintentos no puedan duplicar trabajo.

Errores

Los fallos de autenticación son respuestas HTTP 401 o 403 simples para que los clientes MCP puedan reconocer problemas de credenciales. Los fallos de herramientas son cadenas JSON legibles por máquina con un error y message, y pueden incluir http_status, scope o detalles de límite de velocidad.

Correcciones comunes:

• No aparecen herramientas: verifica la clave con whoami, luego otorga los alcances requeridos.
• insufficient_scope: agrega el alcance nombrado a la clave o elige una herramienta diferente.
• wait_timed_out: llama a wait_for_run nuevamente con el ID de ejecución devuelto.
• thread_busy: espera a que la ejecución activa termine antes de enviar otro mensaje a ese hilo.
• rate_limit_exceeded: espera el intervalo de reintento antes de llamar nuevamente.