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
- 38, 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.
- Tokens
- Unos 8.200 al conectarlo. Ver el detalle.
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.
Codex
codex mcp add ratio --url https://ratioteams.com/api/mcp
Después: codex mcp login ratio. Se abre el navegador para aprobar el acceso en Ratio. Ratio también está en la tienda de complementos de ChatGPT: se puede instalar desde ahí.
ChatGPT
Ratio está en la tienda de complementos de ChatGPT: se instala desde ahí. Para conectarlo a mano:
- En ChatGPT: Configuración → Conectores → Avanzado y activar el modo desarrollador.
- Crear un conector con la dirección
https://ratioteams.com/api/mcpy autenticación OAuth. - Aprobar el acceso en Ratio.
- Abrir un chat nuevo y elegir el conector de Ratio en ese chat: un chat que ya estaba abierto no ve las herramientas.
Lo que ChatGPT puede hacer depende de su modo, no de Ratio. Con el modo desarrollador activo usa todas las herramientas, incluidas las que crean y mueven tareas. Sin ese modo sólo usa search y fetch: puede buscar y leer tareas, pero no cambiarlas. Si el conector aparece conectado y ChatGPT dice que no tiene herramientas, casi siempre es que el modo desarrollador no está activo en esa cuenta o que el chat es anterior a la conexión.
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
401conWWW-Authenticateyresource_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 |
|---|---|---|---|
search |
Busca tareas por texto en todos los proyectos que ve la persona (nombre, descripción, número o proyecto). Devuelve ids para pedir con `fetch`. Sin texto, las últimas. | query (opcional) |
lectura |
fetch |
Una tarea entera por su id (el de `search`, por ejemplo «task:123»): estado, descripción, checklist y comentarios, como texto. | id |
lectura |
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, ícono y enlaces, y si la persona puede escribir tareas (can_write_tasks) o gestionarlo (can_manage). | project_id |
lectura |
update_project |
Edita lo que se manda de un proyecto (lo que no se manda, no se toca): name, description (vacío = ninguna) y status (activo, en_cola, pendiente o listo). Sólo quien gestiona el proyecto. Sacarlo de listo lo reabre. | project_id name (opcional) description (opcional) status (opcional) |
cambia o borra |
set_project_icon |
Le pone ícono al proyecto, con UNA de dos cosas: `icon`, una clave del catálogo del portal (app, web, portal, api, bot, grafico, datos, nube, llave…; vacío = automático) o `image_base64`, una imagen propia (PNG, WebP o JPEG, hasta 400 KB, ya recortada cuadrada). Sólo quien gestiona el proyecto. | project_id icon (opcional) image_base64 (opcional) |
cambia o borra |
list_project_links |
Los enlaces del proyecto (producción, repositorio, documentación…), con su tipo, y cuántos puede tener. | project_id |
lectura |
add_project_link |
Agrega un enlace al proyecto: url (http o https), label (opcional, hasta 60 caracteres) y kind (prod, dev, repo, docs u otro). Hasta 20 por proyecto. Puede quien puede escribir tareas. | project_id url label (opcional) kind (opcional) |
escritura |
update_project_link |
Edita lo que se manda de un enlace del proyecto (label, url, kind); lo demás queda. Los ids salen de list_project_links. | project_id link_id url (opcional) label (opcional) kind (opcional) |
cambia o borra |
delete_project_link |
Saca un enlace del proyecto. | project_id link_id |
cambia o borra |
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. Cada una viene sin su descripción (`has_description` dice si tiene): se lee con `get_task`. Con `include_description` también la trae. | project_id status (opcional) sprint_id (opcional) assignee (opcional) agent_assignee (opcional) include_description (opcional) |
lectura |
get_task |
Una tarea COMPLETA: descripción, checklist, dependencias, archivos, responsables y los últimos comentarios (dice cuántos anteriores hay; `list_comments` los lee). Los registros de trabajo de un agente (kind=log) quedan afuera salvo con include_logs. | task_id comments_limit (opcional) include_logs (opcional) comments_before (opcional) |
lectura |
list_comments |
Los comentarios de una tarea, del más viejo al más nuevo y de a páginas: los últimos `limit`, y `before_id` (del resultado anterior) retrocede una página. kind: all, comment (para personas) o log (registro de un agente). | task_id limit (opcional) before_id (opcional) kind (opcional) |
lectura |
rate_ratio |
Guarda la calificación que la persona le da a Ratio: de 1 a 5 estrellas y un comentario opcional, tal como lo dijo (nunca se completa por ella). declined=true si prefiere no calificar. | stars (opcional) comment (opcional) declined (opcional) |
escritura |
list_docs |
Las páginas de documentación del proyecto (especificación, decisiones, guías), en orden y sin el contenido. La que corresponda se lee con get_doc antes de encarar una tarea. | project_id |
lectura |
get_doc |
Una página de documentación entera, con su contenido en Markdown. | doc_id |
lectura |
create_doc |
Crea una página de documentación en el proyecto, con título y contenido en Markdown. Mencionar #123 enlaza esa tarea. | project_id title body (opcional) |
escritura |
update_doc |
Edita una página: cambia sólo lo que se manda. `body` REEMPLAZA el contenido entero: se lee antes con get_doc y se manda la versión completa. La anterior queda en el historial. | doc_id title (opcional) body (opcional) |
cambia o borra |
get_task_file |
Un adjunto de la tarea, para MIRARLO: una imagen (captura de pantalla) vuelve como imagen y un texto como texto. Los ids salen de `files` en get_task. Otros tipos sólo dicen qué son. | task_id file_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) agent_assignee (opcional) |
escritura |
update_task |
Edita lo que se manda de una tarea (lo que no se manda, 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) agent_assignee (opcional) |
cambia o borra |
set_task_status |
Mueve la tarea de estado. Para bloqueada hace falta block_reason, y si no es un bloqueo sino una pausa a propósito o una espera de respuesta, block_kind on_hold o follow_up. | task_id status block_reason (opcional) block_kind (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. kind=log para las notas de avance de un agente que las personas no necesitan leer (get_task las deja afuera por defecto). | task_id text kind (opcional) |
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 |
Cuánto gasta conectarlo
Ratio no usa ningún modelo de IA por su cuenta: sólo responde a lo que le pide la IA que conectaste. Los tokens los gasta esa IA, dentro del plan de cada persona (el de Claude, el de ChatGPT…), y Ratio no cobra nada por eso: el servidor MCP está incluido en todos los planes. Esto es lo que suma Ratio a una conversación. Son estimaciones, a razón de 1 token cada 3,5 caracteres, sobre lo que el servidor devuelve de verdad.
Al conectarlo
Para que la IA sepa qué puede hacer, el cliente carga la lista de las 38 herramientas de Ratio: unos 8.200 tokens por conversación. Algunos clientes la cargan sólo cuando hace falta usarla. Este número se calcula con la lista real: si cambia una herramienta, cambia acá.
Cada vez que se usa
| Qué se le pide | Herramienta | Tokens (aprox.) |
|---|---|---|
| Saber quién está conectado | whoami | 30 |
| Ver los proyectos | list_projects | 100 |
| Ver un proyecto | get_project | 80 |
| Crear una tarea | create_task | 120 |
| Cambiar el estado de una tarea | set_task_status | 260 |
| Comentar una tarea | add_comment | 20 |
| Leer una tarea con 5 comentarios | get_task | 650 |
| Buscar por texto | search | 900 |
| Listar las tareas de un proyecto | list_tasks | 40 por tarea (10 tareas: 340; 40 tareas: 1.700) |
Medido con tareas de 450 caracteres de descripción: una descripción más larga pesa más. list_tasks devuelve cada tarea sin su descripción (se lee con get_task), así que listar un proyecto grande cuesta poco; con include_description también la trae y cada tarea suma unos 260 tokens. Pedir por estado o por sprint («las tareas en curso del sprint actual») en vez de «todas las tareas» gasta menos todavía.
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
Originde otro sitio se rechaza con403. - Hay un límite de 30 pedidos por segundo por credencial, con ráfagas de hasta 60. Pasado el límite,
429conRetry-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"}'