Ratio Documentación

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)

  1. En Claude: Configuración → Conectores → Agregar conector personalizado.
  2. Nombre: Ratio. Dirección: https://ratioteams.com/api/mcp.
  3. 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:

  1. En ChatGPT: Configuración → Conectores → Avanzado y activar el modo desarrollador.
  2. Crear un conector con la dirección https://ratioteams.com/api/mcp y autenticación OAuth.
  3. Aprobar el acceso en Ratio.
  4. 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.

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.

HerramientaQué haceParámetrosTipo
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 pideHerramientaTokens (aprox.)
Saber quién está conectadowhoami30
Ver los proyectoslist_projects100
Ver un proyectoget_project80
Crear una tareacreate_task120
Cambiar el estado de una tareaset_task_status260
Comentar una tareaadd_comment20
Leer una tarea con 5 comentariosget_task650
Buscar por textosearch900
Listar las tareas de un proyectolist_tasks40 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

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"}'