Servidor MCP

SETTO publica un servidor remoto de Model Context Protocol en https://docs.setto.io/mcp. Expone la API externa como herramientas MCP, así que un asistente puede responder "¿cuántos equipos hay en la categoría Cuarta Fuerza?" llamando a una herramienta en lugar de que tú pegues JSON en un chat, puede configurar un torneo cuando se lo pides (crearlo, agregar sus categorías, inscribir las parejas, sustituir a un jugador, dar de baja a un equipo), puede armar sus grupos y sus eliminatorias y cargar los resultados que le dictas, y puede acomodar un día de partidos de grupos en tus canchas para que tú lo apruebes. Acepta dos tipos de credencial: tu cuenta de SETTO, con un inicio de sesión que la aplicación hace por ti (claude.ai, ChatGPT, Codex, Claude Code), o el mismo token de API que la API REST, personal o de organización. Con tu cuenta, o con un token personal, el asistente ve todos los torneos que administras; con uno de organización, solo los de esa organización.

Endpoint

El servidor es un proxy delgado: reenvía cada llamada de herramienta a la API externa con tu credencial y te devuelve el JSON. Todo lo que la API rechace — un torneo que no alcanzas, una escritura que no permitiste — el servidor MCP también lo rechaza. Cada llamada de herramienta le pregunta de nuevo a la API, así que desconectar una aplicación, revocar un token o dejar una organización surte efecto en la siguiente llamada.

Instalar

Hay dos formas de entrar:

• Con tu cuenta de SETTO — claude.ai, ChatGPT, Codex y Claude Code. No hay nada que crear antes: la aplicación abre SETTO, apruebas lo que puede hacer en app.setto.io, y actúa como tú. claude.ai y ChatGPT solo se conectan así.
• Con un token de API — cualquier cliente que mande una cabecera: Claude Code, Codex, Claude Desktop, Cursor y VS Code. Cursor solo se conecta así.

Entrar con tu cuenta de SETTO

La pantalla de consentimiento lista seis permisos con todos los que pidió la aplicación ya marcados: desmarca lo que no quieras permitir. Ves y desconectas las aplicaciones conectadas en Configuración → Conexiones. El flujo completo, los permisos y la solución de problemas están en Entrar con tu cuenta de SETTO.

Con un token de API

Primero consigue un token: en app.setto.io → Configuración → Tokens de API, deja el selector de cuenta u organización en Personal (o elige una organización) y crea uno; en Permisos, marca «Gestionar torneos» si quieres que el asistente configure torneos (también sus categorías, grupos y cuadros), «Cargar resultados» si quieres que cargue y borre resultados y «Programar partidos» si quieres que pueda colocar partidos. Configuración → Conectar con IA te guía por lo mismo y, justo después de crear un token ahí, te muestra la configuración de cada cliente con ese token ya puesto. Sin un token listo, la instalación en Cursor no se conecta a nada y no avisa.

Ninguno de los dos botones lleva tu token. Cursor lo lee de la variable de entorno SETTO_API_TOKEN; VS Code te lo pide una vez, lo oculta mientras lo escribes y lo guarda. Para Claude Code, usa el plugin o el comando de abajo; para Codex y Claude Desktop, sus pestañas.

claude plugin marketplace add https://docs.setto.io/claude-plugin/marketplace.json
claude plugin install setto@setto

Herramientas

Los argumentos reflejan los parámetros documentados para cada endpoint, incluidos populate, limit/offset, el filtro division y el cursor de list_activity, que pagina hacia atrás desde lo más reciente. Cada herramienta declara las cuatro pistas de MCP: las lecturas (incluidas la propuesta y las cuatro vistas previas) son de solo lectura, idempotentes y no destructivas; una creación (un torneo, una categoría, una inscripción) no es idempotente, porque llamarla dos veces agrega dos; una edición, una publicación, las cabezas de serie, agregar las eliminatorias y un resultado son idempotentes y no destructivos; un borrado, el ciclo de vida, la «Sustitución», la «Baja», la escritura de la programación, aplicar un formato, unos grupos o un cuadro, «Confirmar cuadro», quién juega un partido y borrar un resultado son destructivos e idempotentes; y ninguna sale de tu cuenta de SETTO (openWorldHint: false). Guías de las lecturas: listar torneos, obtener un torneo, listar categorías, listar equipos, obtener una ronda.

Programar partidos con un asistente

El asistente puede llenar un día de partidos de grupos «un grupo por cancha»: cada grupo juega sus partidos seguidos en la misma cancha, las canchas en paralelo llevan categorías distintas, las peticiones de horario de los equipos deciden la ventana de cada grupo, y nadie queda en dos lugares a la vez — ni siquiera un jugador inscrito en dos categorías. La propuesta no mueve los partidos ya programados; solo acomoda los que faltan alrededor de ellos. Aplicar es distinto: apply_schedule_placements sí puede mover cualquier partido programado que todavía no se haya jugado, por eso escribe exactamente lo que apruebas.

Siempre va en este orden, y las instrucciones del servidor se lo enseñan al modelo:

1. get_schedule — canchas, categorías, todos los partidos (y cuáles están bloqueados: jugados, con resultado o ya empezados) y las peticiones aprobadas.
2. propose_pool_per_court_schedule — un plan para un día. No guarda nada. Lista los partidos colocados, los que no pudo colocar y cada equipo que tuvo que poner fuera de un horario que prefería.
3. Tú lo revisas. El asistente te muestra los partidos de cada cancha con su horario, los que quedaron sin colocar y las peticiones no cumplidas, y espera tu sí.
4. apply_schedule_placements — escribe exactamente lo que aprobaste. Todo o nada: si algo choca (una cancha, un equipo o una persona dos veces a la vez, o una petición de no puede jugar), no se escribe nada y el asistente recibe la lista completa de partidos en conflicto para mostrártela.

El permiso «Programar partidos»

Aplicar una programación requiere «Programar partidos» (schedule), uno de los seis permisos que puede llevar un inicio de sesión o un token:

• Con tu cuenta de SETTO: deja «Programar partidos» marcado en la pantalla de consentimiento de SETTO. La aplicación programa entonces cualquier torneo que administres, mientras lo administres.
• Un token personal: marca «Programar partidos» en Permisos al crearlo en app.setto.io → Configuración → Tokens de API; la lista de tokens lo señala con «Programa partidos». Programa cualquier torneo que administres, mientras lo administres.
• Un token de organización con el permiso solo lo puede crear un ADMIN de la organización, y funciona solo mientras esa persona siga siendo ADMIN de la organización.

Cualquier otra credencial lee — incluido el paso 2, que no escribe nada — y recibe 403 INSUFFICIENT_SCOPE en el paso 4, que el asistente te reporta, con la solución para su tipo de credencial, en lugar de reintentar. Una aplicación conectada con tu cuenta obtiene el permiso al conectarla otra vez y dejarlo marcado.

Usa un token de solo lectura, o desmarca «Programar partidos» al entrar con tu cuenta, donde solo necesites respuestas, y guarda una credencial de programación para las sesiones en las que planeas días.

Configurar un torneo con un asistente

Pídelo con tus palabras — "crea la Copa Primavera, pádel, 14 y 15 de marzo en Ciudad de México, con 4a varonil y 5a femenil", "inscribe estas ocho parejas en 4a", "Luis Ruiz entra por Juan Pérez en su pareja", "Pérez / Soto se dan de baja" — y el asistente lo convierte en las herramientas de arriba. Crea torneos con el plan gratis, en borrador («Borrador»: 2 categorías, 12 parejas o 24 jugadores en individuales), agrega y edita categorías y sus cabezas de serie («Cabezas de serie»), inscribe equipos uno por uno o hasta 50 a la vez, edita equipos y jugadores, sustituye a un jugador («Sustitución») y da de baja a un equipo («Baja»). Publica, regresa a borrador, archiva o restaura un torneo solo cuando se lo pides. Los planes de pago, los precios, los pagos y los torneos de fútbol se quedan en el panel.

Las reglas de las escrituras

• Los nombres se vuelven ids leyendo primero. El asistente encuentra el torneo, la categoría, el equipo o el jugador que nombras con list_tournaments y search_tournament. Cuando dos del mismo tipo encajan (dos jugadores llamados Juan Pérez), la respuesta dice ambiguous y el asistente te pregunta cuál es.
• «Vista previa» antes de una baja. preview_team_withdrawal no escribe nada: lista cada partido del equipo y lo que la «Baja» le hace — un W.O. para un rival conocido, un pase («BYE») para un rival que aún no se decide, un partido por un puesto que se decide de inmediato, o un partido que queda como está para que registres el resultado en el panel cuando se sepa el rival. Cada partido trae esa consecuencia en español. El asistente te muestra la lista y espera tu sí.
• Tu sí es la confirmación. withdraw_team aplica exactamente el plan que viste: lleva la confirmación de la vista previa, válida 15 minutos, para ese equipo y ese plan. Si el torneo cambió en medio, no se escribe nada y el asistente vuelve a pedir la vista previa. Una categoría o un equipo se borra también solo después de tu sí (confirm: true), y solo si está vacío: un equipo con partidos sale con una «Baja», que conserva sus resultados jugados.
• Un reintento nunca escribe dos veces. Cada creación y cada operación de equipo lleva una llave de idempotencia, así que una llamada repetida tras un tiempo de espera contesta el primer resultado en lugar de crear un segundo torneo o inscribir dos veces a una pareja.
• Los límites los subes tú. Una categoría o un equipo de más para el plan se rechaza antes de escribir nada, y el asistente te dice que mejores el plan en el panel («mejora el plan en el panel»). Un organizador crea a lo mucho 20 torneos al día por la API.
• Todo queda en la «Actividad». Cada escritura, y cada rechazo, queda registrado con quién actuó y con qué aplicación o token; list_activity lo lee. Inscribir no envía ningún correo, y nada de esto cambia ningún precio, marca de pago, registro de pago ni reembolso; una baja cierra los enlaces de pago sin pagar del equipo. Cuando el equipo de un jugador sustituido tiene marcas de pago, la respuesta dice «revisa los pagos de este equipo en el panel».

El permiso «Gestionar torneos»

Configurar torneos requiere «Gestionar torneos» (manage), igual que programar requiere «Programar partidos»: déjalo marcado en la pantalla de consentimiento de SETTO al entrar con tu cuenta, o márcalo en Permisos al crear un token; un token de organización con él funciona solo mientras quien lo creó siga siendo ADMIN. Sin él, cada escritura de configuración responde 403 INSUFFICIENT_SCOPE, mientras que la búsqueda y la vista previa de la baja, que no escriben nada, siguen funcionando.

Cuadros y resultados con un asistente

Pídelo como se lo pedirías a un colega — "4a varonil juega fase de grupos y luego eliminatorias, a mejor de tres sets", "arma 2 grupos", "mueve a Los Tigres al Grupo B", "pasan los dos primeros de cada grupo", "confirma el cuadro", "carga 6-3 6-4 para Pérez / López contra Ruiz / Gómez" — y el asistente sigue los mismos pasos que «Formato», «Configurar grupos», «Configurar eliminatorias» y «Confirmar cuadro» del panel, y luego carga los resultados. Funciona en las categorías de pádel, tenis y pickleball de un torneo regular; las clasificatorias («Clasificatoria»), armar partidos de consolación, las ligas y el fútbol se quedan en el panel, mientras que los resultados y quién juega cada partido funcionan en cualquier partido de eliminatorias, el de tercer lugar y los de consolación incluidos.

1. El formato (preview_division_format y luego apply_division_format): fase de grupos («Fase de Grupos»), eliminatorias («Eliminatorias») o ambas, a 1, 2 o 5 sets. Las rondas que conservan su tipo conservan sus partidos y resultados, y una ronda con resultados nunca se reemplaza. Una categoría que ya juega sus grupos recibe sus eliminatorias con append_elimination_round, que conserva cada partido de grupos.
2. Los grupos (preview_pools y luego apply_pools): los equipos aceptados de la categoría repartidos en grupos, las cabezas de serie separadas y el resto por sorteo, con todos sus partidos. "Mueve a Los Tigres al Grupo B" es una vista previa nueva con el mismo sorteo: Los Tigres cambian de lugar con un equipo del Grupo B y los demás se quedan donde estaban.
3. El cuadro de eliminatorias (preview_draw y luego apply_draw): después de una fase de grupos, lugares como «1ro Pool A» o «2do de 1ros», con «Clasificación entre grupos» o «Clasificación de grupos»; en eliminatorias directas, los equipos mismos, primero las cabezas de serie. Los BYE van a los mejores lugares, y el partido por el tercer lugar es opcional. Un cuadro admite hasta 256 equipos.
4. «Confirmar cuadro» (confirm_draw), cuando cada partido de grupos ya tiene resultado: cada lugar recibe al equipo que nombra la clasificación final.
5. Resultados (record_game_result): el asistente lee primero el partido, para que los sets vayan en su orden de local y visitante, y luego te dice qué cambió: la clasificación, o quién avanzó en el cuadro.

Las reglas de los cuadros y los resultados

• Ves cada plan antes de que se escriba. Un formato, unos grupos o un cuadro se previsualizan primero y no se guarda nada: el asistente te muestra cada grupo con sus equipos, la primera ronda del cuadro y todo lo que reemplazaría, y espera tu sí. La aplicación lleva la confirmación de la vista previa, válida 15 minutos, y escribe exactamente ese plan; si la categoría cambió en medio, no se escribe nada y el asistente vuelve a pedir la vista previa.
• Lo jugado nunca se reconstruye. Un formato, unos grupos o un cuadro que reemplazarían partidos con resultado se rechazan, y un cuadro con resultados nunca se vuelve a armar ni a acomodar.
• Un equipo dado de baja nunca entra al cuadro. Cuando la clasificación final pone a un equipo dado de baja («Baja») en las eliminatorias, el asistente te pregunta quién toma su lugar: otro equipo de la categoría, o un BYE que manda a su rival directo a la siguiente ronda.
• Un resultado guardado solo cambia con tu palabra. Cuando un partido ya tiene resultado, el asistente te lo muestra y te pregunta antes de reemplazarlo, y borrar un resultado («Borrar resultado») también espera tu sí. Los W.O. de un equipo dado de baja se quedan, y un resultado que subió un jugador se aprueba o se rechaza en el panel.
• Las advertencias llegan en español: un número de sets raro para el formato de la ronda, un resultado de grupos que cambió después de confirmar el cuadro, o un torneo cuya clasificación todavía no suma puntos.

El permiso «Cargar resultados»

Cargar y borrar resultados requiere «Cargar resultados» (results): déjalo marcado en la pantalla de consentimiento de SETTO al entrar con tu cuenta, o márcalo en Permisos al crear un token; un token de organización con él funciona solo mientras quien lo creó siga siendo ADMIN. El formato, los grupos, el cuadro, su confirmación y quién juega un partido requieren «Gestionar torneos», y sus vistas previas, que no escriben nada, solo «Leer». Sin el permiso, una escritura responde 403 INSUFFICIENT_SCOPE y el asistente te dice cuál falta.

Cómo se conecta cada cliente

Cursor termina un inicio de sesión volviendo a una dirección cursor://, y el inicio de sesión de SETTO solo regresa a direcciones https:// y locales (http://localhost), así que por ahora Cursor usa un token. Donde ninguna de las dos formas sirva, hay dos alternativas que funcionan en todos los clientes:

• El Agent Skill — setto-api le enseña a cualquier agente los mismos endpoints y hace llamadas HTTP normales.
• La API REST directamente — consulta el inicio rápido.

Notas de seguridad

• Ninguna credencial llega al modelo. Al entrar con tu cuenta, el token de acceso se queda en la aplicación, nunca en la conversación, y un token va en la configuración del cliente. Nunca pegues un token en una conversación — un token pegado termina en la transcripción y, según tu configuración, en los logs.
• Usa el entorno o el aviso de secretos del cliente. $SETTO_API_TOKEN en Claude Code, --bearer-token-env-var en Codex, ${env:…} en Cursor, un inputs en VS Code. No commitees una configuración MCP con un token literal adentro. La configuración de Claude Desktop es la excepción que sí lo guarda: mantén ese archivo privado, o usa el conector personalizado.
• Las escrituras van detrás de un permiso y de tu confirmación. La escritura de la programación (apply_schedule_placements) solo fija horarios, canchas y duración de partidos, no puede mover un partido jugado y rechaza una programación con choques; requiere «Programar partidos». Las escrituras de configuración (torneos, categorías, cabezas de serie, equipos, jugadores, «Sustitución», «Baja») y las de los cuadros (formatos, grupos, eliminatorias, quién juega un partido) requieren «Gestionar torneos», y cargar o borrar un resultado requiere «Cargar resultados». Ninguna envía correos, y con ellas no cambia ningún precio, marca de pago, registro de pago ni reembolso (una baja cierra los enlaces de pago sin pagar del equipo). Las destructivas están marcadas así, y la mayoría de los clientes piden confirmación antes de correrlas, salvo que las hayas aprobado siempre; una baja, un formato, unos grupos y un cuadro además necesitan la confirmación que entrega su vista previa. Sin esos tres permisos, un modelo confundido o con prompt injection no puede cambiar nada.
• Puedes ver y detener todo. Cada cambio que hace una aplicación o un token queda registrado en «Actividad», y un asistente puede leerla con list_activity ("¿qué cambiaste ayer?"). Desconectar en Configuración → Conexiones le corta el acceso a una aplicación conectada con tu cuenta de inmediato; revocar un token en Tokens de API hace lo mismo con ese token.
• Acota lo que puedas. Tu cuenta, o un token personal, alcanza todos los torneos que administras; uno de organización alcanza esa organización y nada más. Da solo los permisos que necesites. Para algo compartido — un asistente que usan varias personas, o uno que no controlas del todo — prefiere un token de organización o uno de solo lectura, y crea un token dedicado para poder revocarlo solo.
• Cuenta contra tu límite de uso. Las llamadas de herramienta son peticiones a la API: 120 por 60 segundos por token, compartidas con cualquier otra cosa que use ese token. Consulta Límites de uso.

Conversaciones de ejemplo

Tú: ¿Qué categorías del Torneo Apertura 2026 todavía tienen partidos sin jugar?

Asistente: llama a list_tournaments con status: "IN_PROGRESS" — encontré Torneo Apertura 2026 (3c9b7f52-…).

llama a list_divisions con ese torneo y populate: "rounds" — tres categorías, cinco rondas entre ellas.

llama a get_round para cada ronda con populate: "games" —

Cuarta Fuerza Varonil tiene 4 de 12 partidos todavía en UPCOMING; Primera Fuerza Femenil está completa; Mixta B tiene 1 partido pendiente, programado el sábado a las 10:00.

Tú: Programa los partidos de grupos del sábado de Cuarta Fuerza y Mixta B en las canchas 1 y 2, desde las 9:00, un grupo por cancha.

Asistente: llama a get_schedule y luego a propose_pool_per_court_schedule con day: "2026-11-07", start: "09:00" y los idx de las dos canchas —

Cancha 1: Cuarta Fuerza grupo A, 6 partidos, 9:00–15:00. Cancha 2: Mixta B grupo A, 9:00–12:00, y luego el grupo B, 12:00–15:00. Caben todos. Una petición no cumplida: Pérez / Gómez prefieren jugar después de las 11:00 y su primer partido es a las 10:00. ¿Lo aplico?

Tú: Sí.

Asistente: llama a apply_schedule_placements con esos 12 partidos — listo, 12 partidos programados.

Tú: Pérez / Soto se dan de baja de 4a varonil.

Asistente: llama a search_tournament con q: "pérez soto" y luego a preview_team_withdrawal —

Jugaron 2 partidos (sus resultados se quedan). Partido 7 contra Ruiz / Gómez: W.O. a favor de Ruiz / Gómez. Cuartos de final, partido 12, con el rival aún por decidir: queda como BYE, y quien llegue pasa directo. ¿Los doy de baja?

Tú: Sí.

Asistente: llama a withdraw_team con la confirmación de la vista previa — listo: un W.O. registrado, un BYE puesto y la inscripción cancelada.

Tú: Arma 2 grupos en 4a varonil.

Asistente: llama a search_tournament con q: "4a varonil", luego a list_divisions con populate: ["rounds"] y a preview_pools con numberOfPools: 2 —

Grupo A: Pérez / López, Ruiz / Gómez, Soto / Díaz, Mora / Vega. Grupo B: Luna / Ríos, Cruz / Peña, Lara / Gil, Paz / Ortiz. 12 partidos, todos contra todos una vez en su grupo; no se reemplaza nada. ¿Lo aplico?

Tú: Antes mueve a Cruz / Peña al Grupo A.

Asistente: vuelve a llamar a preview_pools con ese cambio y el mismo rngSeed — Grupo A: Pérez / López, Ruiz / Gómez, Cruz / Peña, Mora / Vega. Grupo B: Luna / Ríos, Soto / Díaz, Lara / Gil, Paz / Ortiz. ¿Lo aplico?

Tú: Sí.

Asistente: llama a apply_pools con la confirmación de la vista previa — listo: dos grupos, 12 partidos.

Tú: Carga 6-3 6-4 para Pérez / López contra Ruiz / Gómez.

Asistente: llama a get_round para encontrar el partido, su local y su visitante, y luego a record_game_result con los sets en ese orden — cargado: Pérez / López ganan en dos sets y van primeros del Grupo A.

Si un número se ve raro, pregúntale al asistente qué llamada de herramienta lo produjo y revisa ese endpoint a mano.

Relacionado

• Entrar con tu cuenta de SETTO — el flujo de OAuth, los seis permisos, «Conexiones» y «Actividad».
• Agent Skills — la alternativa agnóstica al cliente, y qué instalar cuando MCP no es opción.
• Documentación para LLMs — llms.txt, Markdown por página, /openapi.json.
• Límites de uso — el presupuesto que comparten tus llamadas de herramienta.