Servidor MCP de Ratio

Ratio tiene un servidor MCP (Model Context Protocol) oficial y remoto. Con él, un asistente de IA ve los proyectos de la persona que lo conectó y trabaja en ellos —consulta, crea y actualiza tareas, comenta, maneja sprints— con sus mismos permisos.

Dirección: https://ratioteams.com/api/mcp
Transporte: Streamable HTTP, JSON-RPC 2.0. Respuestas en JSON, sin sesión.
Autenticación: OAuth 2.1 con PKCE y registro dinámico de clientes, o una clave de API personal.
Herramientas: 23, de lectura y de escritura. Ver la lista.
Protocolo: Versiones 2025-06-18, 2025-03-26 y 2024-11-05.
Precio: Incluido en todos los planes, también en el gratuito.

Conectar un cliente

Claude (web, escritorio y celular)

En Claude: Configuración → Conectores → Agregar conector personalizado.
Nombre: Ratio. Dirección: https://ratioteams.com/api/mcp.
Al conectar se abre Ratio para iniciar sesión y aprobar el acceso. No hace falta ninguna clave.

Claude Code

claude mcp add --scope user --transport http ratio https://ratioteams.com/api/mcp

Después, dentro de Claude Code: /mcp → ratio → Authenticate. Se abre el navegador para aprobar el acceso en Ratio.

ChatGPT

En ChatGPT: Configuración → Conectores → Avanzado y activar el modo desarrollador.
Crear un conector con la dirección https://ratioteams.com/api/mcp y autenticación OAuth.
Aprobar el acceso en Ratio.

Cursor

En Settings → MCP → Add server, o en ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ratio": { "url": "https://ratioteams.com/api/mcp" }
  }
}

Otros clientes

Cualquier cliente con soporte para servidores MCP remotos por HTTP sirve. Si el cliente no maneja OAuth, se puede usar una clave de API personal en el encabezado:

{
  "mcpServers": {
    "ratio": {
      "type": "http",
      "url": "https://ratioteams.com/api/mcp",
      "headers": { "Authorization": "Bearer ${RATIO_API_KEY}" }
    }
  }
}

Las claves se generan en el portal, en Credenciales. Empiezan con tasks_fk_ y se muestran una sola vez.

Autenticación

El servidor acepta dos credenciales, siempre en Authorization: Bearer …. Nunca acepta la cookie del navegador: lo que se conecta por MCP es un agente, no una persona en la pantalla.

OAuth 2.1 (recomendado). Ratio es su propio servidor de autorización, con registro dinámico de clientes y PKCE S256. Un pedido sin credencial responde 401 con WWW-Authenticate y resource_metadata, y el cliente arranca el inicio de sesión solo. El token de acceso dura una hora y se renueva con un refresh token de 30 días. Los tokens OAuth sirven sólo para el servidor MCP.
Clave de API personal (tasks_fk_…). La misma que usa la API REST.

Los metadatos están en https://ratioteams.com/.well-known/oauth-protected-resource y https://ratioteams.com/.well-known/oauth-authorization-server.

Herramientas

Cada herramienta llama a la misma función que la API REST, con los mismos permisos. Las de lectura llevan readOnlyHint; las que cambian o borran algo, destructiveHint, para que el cliente pida confirmación antes de usarlas.

Herramienta	Qué hace	Parámetros	Tipo
`whoami`	La cuenta de Ratio conectada: id, nombre y mail de la persona.	—	lectura
`list_spaces`	Los espacios de la persona, con su rol en cada uno (dueno, miembro o lector).	—	lectura
`list_people`	La gente con la que comparte algún espacio. Con space_id, sólo la de ese espacio y con su rol: es lo que hace falta para asignar (se asigna a dueños y miembros del espacio del proyecto).	`space_id` (opcional)	lectura
`list_projects`	Los proyectos que ve la persona (los de sus espacios), con su espacio y su rol.	`space_id` (opcional)	lectura
`get_project`	Un proyecto: datos, y si podés escribir tareas (can_write_tasks) o gestionarlo (can_manage).	`project_id`	lectura
`list_task_types`	Los tipos de tarea que se pueden usar en ese proyecto (bug, feature, mejora…).	`project_id`	lectura
`list_modules`	Los módulos del proyecto (partes de un proyecto grande).	`project_id`	lectura
`list_sprints`	Los sprints del proyecto, con cuál está en curso.	`project_id`	lectura
`create_sprint`	Crea un sprint en el proyecto. Sin name, se le pone el número que sigue.	`project_id` `name` (opcional) `starts_on` (opcional) `ends_on` (opcional) `traer_backlog` (opcional)	escritura
`close_sprint`	Cierra un sprint. Lo que quedó sin terminar no se pierde: va a `destino` (id de otro sprint, "backlog" o "hechas"); sin destino, al siguiente sprint abierto o al backlog.	`sprint_id` `destino` (opcional)	cambia o borra
`list_tasks`	Las tareas del proyecto, con filtros opcionales.	`project_id` `status` (opcional) `sprint_id` (opcional) `assignee` (opcional)	lectura
`get_task`	Una tarea COMPLETA: descripción, comentarios, checklist, dependencias, archivos y responsables.	`task_id`	lectura
`create_task`	Crea una tarea: nace pendiente y en el backlog, salvo que venga sprint_id. El tipo sale de list_task_types.	`project_id` `name` `description` (opcional) `tipo` (opcional) `module_id` (opcional) `sprint_id` (opcional) `due_date` (opcional) `color` (opcional) `assignee_ids` (opcional)	escritura
`update_task`	Edita lo que mandes de una tarea (lo que no mandás, no se toca): name, description, tipo, module_id, sprint_id (0 = backlog), due_date, color, assignee_ids. El estado va con set_task_status.	`task_id` `name` (opcional) `description` (opcional) `tipo` (opcional) `module_id` (opcional) `sprint_id` (opcional) `due_date` (opcional) `color` (opcional) `assignee_ids` (opcional)	cambia o borra
`set_task_status`	Mueve la tarea de estado. Para bloqueada, mandá block_reason.	`task_id` `status` `block_reason` (opcional)	cambia o borra
`delete_task`	Borra una tarea para siempre, con sus comentarios y su checklist. Sólo puede quien gestiona el proyecto.	`task_id`	cambia o borra
`add_comment`	Comenta en una tarea (en Markdown). Alcanza con ver el proyecto.	`task_id` `text`	escritura
`update_comment`	Reescribe un comentario. Sólo quien lo escribió.	`comment_id` `text`	cambia o borra
`delete_comment`	Borra un comentario, con sus archivos. Quien lo escribió o quien gestiona el proyecto.	`comment_id`	cambia o borra
`add_checklist_item`	Suma un ítem a la checklist de una tarea.	`task_id` `text`	escritura
`update_checklist_item`	Tilda, destilda o reescribe un ítem de la checklist.	`check_id` `done` (opcional) `text` (opcional)	cambia o borra
`add_dependency`	La tarea task_id queda esperando a depends_on (no puede arrancar hasta que esa termine).	`task_id` `depends_on`	escritura
`remove_dependency`	Saca la dependencia: task_id deja de esperar a depends_on.	`task_id` `depends_on`	cambia o borra

Permisos y seguridad

El asistente actúa como la persona que lo conectó: ve sólo sus espacios y proyectos, y su rol en cada espacio (lector, miembro o dueño) decide qué puede hacer. Lo de un espacio ajeno responde como si no existiera.
Todo lo que hace queda en el historial de cada tarea a nombre de esa persona, marcado «vía API».
El rol se revisa en cada pedido: si a la persona la pasan a lector o la sacan del espacio, el asistente pierde el acceso en el acto.
Las conexiones se ven y se cortan desde Credenciales, en el portal. Desconectar quita el acceso al momento.
Un pedido con un Origin de otro sitio se rechaza con 403.
Hay un límite de 30 pedidos por segundo por credencial, con ráfagas de hasta 60. Pasado el límite, 429 con Retry-After.

Errores

Un error de la operación —falta de permiso, algo que no existe, un dato mal armado— vuelve como resultado de la herramienta con isError: true y el motivo en texto, para que el asistente lo lea y corrija. Los errores del protocolo siguen JSON-RPC: -32601 para un método que no existe y -32700 para un JSON roto.

Ejemplo

Listar las herramientas con una clave de API:

curl -s https://ratioteams.com/api/mcp \
  -H "Authorization: Bearer $RATIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

API REST →