Conectá tu app a cliply

Tu app puede leer los datos de cliply de un entrenador igual que Claude y ChatGPT: por el servidor MCP de cliply, con la autorización del propio entrenador. No necesitás una API key nuestra ni pedirnos que te registremos. Tu app se registra sola, el entrenador la aprueba y llamás a las tools con el token que recibís.

Tu app recibe datos en JSON: partidos, tags, hechos, estadísticas, secuencias, jugadores e ids de clips. Nunca recibe video. El video se reproduce en cliply, y cada id de clip se convierte en un link que abre el workbench de cliply en esa jugada.

De un vistazo

Inicio rápido con el SDK de MCP

Los SDKs oficiales de MCP traen un cliente que descubre los endpoints, registra tu app y resuelve el flujo OAuth. En TypeScript (@modelcontextprotocol/sdk):

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

// authProvider implements OAuthClientProvider: it stores the client
// registration, the PKCE verifier and the tokens per coach, and redirects
// the coach's browser to the authorize URL.
const transport = new StreamableHTTPClientTransport(
  new URL("https://cliply.video/api/mcp"),
  { authProvider },
);
const client = new Client({ name: "your-app", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
const result = await client.callTool({
  name: "list_matches",
  arguments: {},
});

De tu lado queda: un botón Conectar cliply, una ruta de callback, guardar los tokens de cada entrenador y el provider de arriba. El resto de esta página explica lo que hace el SDK, para los equipos que arman el flujo a mano.

El flujo OAuth, paso a paso

1. Descubrir

GET https://cliply.video/.well-known/oauth-protected-resource/api/mcp nombra al servidor de autorización, y su documento de metadata lista todos los endpoints de la tabla de arriba. Un 401 de /api/mcp trae el mismo puntero en el header WWW-Authenticate.

2. Registrar tu app (una vez)

POST https://cliply.video/api/auth/oauth2/register
Content-Type: application/json

{
  "client_name": "Your App",
  "redirect_uris": ["https://yourapp.example/cliply/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Guardá el client_id que recibís y usá el mismo para todos los entrenadores. No te registres de nuevo por cada uno. El registro tiene límite de frecuencia.

3. Mandar al entrenador a cliply

Cuando el entrenador elige Conectar cliply, redirigí su browser a:

https://cliply.video/api/auth/oauth2/authorize
  ?response_type=code
  &client_id=<client_id>
  &redirect_uri=https://yourapp.example/cliply/callback
  &scope=cliply:read cliply:write offline_access
  &code_challenge=<S256 challenge>
  &code_challenge_method=S256
  &state=<random>
  &resource=https://cliply.video/api/mcp

De este paso se encarga cliply. El entrenador inicia sesión (o crea una cuenta y una organización), elige la organización que va a leer la conexión y aprueba.

4. Canjear el código

cliply vuelve a tu redirect_uri con code y tu state. Comprobá que state coincida con el que mandaste y canjeá el código:

POST https://cliply.video/api/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<code>
&redirect_uri=https://yourapp.example/cliply/callback
&client_id=<client_id>
&code_verifier=<PKCE verifier>
&resource=https://cliply.video/api/mcp

La respuesta trae un access_token y, si pediste offline_access, un refresh_token. Guardá los dos asociados al entrenador.

5. Renovar

Cuando vence el access token, pedí uno nuevo con grant_type=refresh_token, tu client_id y el refresh token. El entrenador no ve este paso. Guardá el refresh token que devuelve la respuesta: puede ser distinto del que mandaste.

Scopes y qué aprueba el entrenador

• cliply:read: lee todo lo que el entrenador ve en la organización que eligió.
• cliply:write: opcional. Permite crear colecciones y presentaciones y comentar clips. Nunca edita ni borra nada. La pantalla de autorización lo muestra como un casillero que el entrenador puede desmarcar. Si lo desmarca, el token queda en solo lectura y las tools de creación no aparecen.
• offline_access: emite un refresh token.

Cada token queda atado a un entrenador y una organización. Ve lo que ese entrenador ve ahí (los proyectos privados, solo si el entrenador puede abrirlos) y nunca usa otra membresía. Las cuentas de jugador no pueden autorizar. Para leer otra organización, el entrenador vuelve a conectar y la elige.

La pantalla de autorización muestra el client_name que registraste junto al host de tu redirect_uri. Registrá un nombre que los entrenadores reconozcan.

Llamar a las tools

Cada llamada es un pedido JSON-RPC a /api/mcp con el token del entrenador:

POST https://cliply.video/api/mcp
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"match_analysis","arguments":{"matchId":"<id>"}}}

El servidor no guarda estado, así que no necesitás session id. Un token revocado se rechaza en el pedido siguiente. Llamá a tools/list para ver el esquema actualizado de cada tool; ahí cada una trae también su input.

Algunas lecturas dependen de funciones que la organización tenga activadas, como GPS, estadísticas del banco o estadísticas de temporada. Si una está apagada, la tool lo dice en vez de devolver datos.

Links y citas

• Los tiempos son segundos desde el inicio del video.
• Un partido se linkea con su url. Una jugada, con la url del partido más ?clip=<clipId>; cualquier id de clip de cualquier lectura funciona ahí.
• Los hechos de match_analysis traen ids (F1, F2…). Citalos para que el entrenador pueda rastrear cada afirmación hasta el partido.
• Los links abren el workbench de cliply y piden que el entrenador tenga sesión iniciada en cliply. Para mostrarles clips a los jugadores, creá una colección con cliply:write y el entrenador la comparte desde cliply.
• Tu modelo lee tags, no video. Las respuestas son tan completas como el etiquetado del entrenador.

Límites, créditos y errores

• Límites de frecuencia: 120 pedidos por minuto por entrenador y 300 por minuto por IP. Si te pasás, /api/mcp responde 429 con Retry-After: 60.
• Créditos: las lecturas por el conector no consumen créditos de cliply.
• 401: falta el token, venció o fue revocado. Renovalo, o mandá al entrenador a hacer el flujo de nuevo.
• Errores de una tool: vuelven como un resultado normal con isError: true y un mensaje que tu modelo puede leer.

Desconectar

Un entrenador desconecta tu app en cliply desde Cuenta → Sesiones → Apps de IA. Los propietarios y admins de la organización pueden desconectar la app de cualquier miembro desde Configuración de la organización → General → Apps de IA, y el registro de auditoría de la organización anota cada conexión. Tu app también puede revocar sus propios tokens en el endpoint de revocación. En todos los casos, la siguiente llamada con ese token recibe un 401.

Para consultas, escribinos a hi@cliply.video.