Integración avanzada de MCP
Requisitos del cliente, configuración de Codex CLI, transporte y referencia OAuth.
API v2ActualReferencia para desarrollar un cliente o revisar su compatibilidad. Si tu aplicación ya admite MCP remoto con OAuth, seguí el inicio rápido.
Comprobá la compatibilidad
La conexión está verificada localmente con el cliente TypeScript del SDK oficial de MCP 1.31.x: autorización OAuth, listado de herramientas, consultas y renovación. Esto no confirma compatibilidad con todas las aplicaciones o versiones.
El cliente necesita Streamable HTTP remoto y OAuth Authorization Code con PKCE S256, descubrimiento de metadata y registro dinámico (DCR) como cliente público con token_endpoint_auth_method: none. Debe enviar resource y gestionar la renovación de tokens.
No se admiten client_secret, el flujo client_credentials ni registro mediante Client ID Metadata Documents. Para un cliente propio, implementá el proveedor OAuth del SDK; un token fijo no resuelve la autorización ni su renovación.
No hay sandbox MCP. La URL pública utiliza datos reales y el cupo de la cuenta; comprobá la disponibilidad en Asistentes IA antes de integrar.
Guías de clientes y opciones de Codex
La guía de inicio incluye la configuración de Codex CLI, OpenCode 2, Claude Code y Kimi Code CLI, con enlaces a sus instrucciones oficiales. Esas guías no equivalen a una validación de extremo a extremo con Clasificar; esa comprobación sigue pendiente.
En Codex, la sintaxis también se contrastó con la CLI 0.160.0. Si necesitás elegir el registro dinámico explícitamente, usá el comando siguiente después de agregar el servidor:
codex mcp login clasificar --oauth-client-registration dcrTransporte y comprobación del acceso
Usá https://api.clasific.ar/mcp como dirección de Streamable HTTP. El transporte no mantiene sesiones: cada solicitud MCP usa POST con respuesta JSON. No hay un stream SSE independiente por GET.
Inicializá el cliente y ejecutá tools/list para comprobar la conexión. No uses consultar_vehiculo ni consultar_modulos para esto: consumen cupo.
Las solicitudes llevan el token de acceso en el encabezado Authorization. Los clientes de navegador requieren un origen permitido por el servicio; consultá a soporte si tu integración necesita ese acceso.
Seguí operaciones asíncronas
Los módulos se procesan de forma asíncrona. Guardá operation.id de la respuesta y usalo como id en consultar_operacion. Si sigue en curso, esperá antes de volver a consultar el estado. No inicies otra consulta para recuperar un resultado.
Una solicitud de módulos idéntica que sigue en curso se reutiliza dentro de la misma cuenta, incluso entre API y MCP y entre distintas credenciales. El orden de los módulos no cambia el conjunto solicitado. No se descuentan unidades adicionales; la operación conserva el canal que la inició.
Volver a solicitar módulos después de que la operación terminó inicia una consulta nueva y vuelve a consumir unidades. Esta reutilización no exime del consumo de una consulta básica de vehículo.
Implementá el flujo OAuth
Esta referencia es para quien desarrolla un cliente. El usuario conecta desde su asistente y aprueba en Clasificar; no necesita copiar tokens ni construir estas solicitudes.
Usá https://api.clasific.ar/mcp como resource en producción. Descubrí los endpoints mediante metadata; las rutas de la tabla pertenecen al origen del servidor MCP, no al sitio público. No agregues parámetros a la URL de transporte.
| Endpoint | Función |
|---|---|
GET /.well-known/oauth-protected-resource/mcp | Identifica el recurso, los scopes y los servidores de autorización. El desafío 401 del MCP indica esta metadata en WWW-Authenticate. |
GET /.well-known/oauth-authorization-server | Publica issuer, endpoints y soporte de PKCE S256. |
POST /register | Recibe JSON y devuelve la identidad del cliente público. Requiere redirect_uris y token_endpoint_auth_method: none; client_name es opcional. |
GET /authorize | Recibe client_id, response_type=code, retorno registrado, desafío PKCE S256, resource, y opcionalmente scope y state. Abre el consentimiento. |
POST /token | Intercambia código o refresh token mediante formulario URL-encoded. |
POST /revoke | Recibe client_id y token mediante formulario URL-encoded. Revoca la autorización completa asociada a ese token del cliente. |
Registro y retorno
Registrá de una a cinco URLs de retorno. Deben usar HTTPS o HTTP de loopback local, sin usuario, contraseña ni fragmento. El retorno debe coincidir con el registrado; se admite un puerto variable en loopback local. En el intercambio del código, enviá exactamente el retorno usado al autorizar.
El cliente genera y conserva un code_verifier, envía su desafío S256 y comprueba el state al volver. Si el usuario cancela, el retorno incluye error=access_denied y conserva el state recibido; no se emite un código.
Intercambio de código y renovación
| Solicitud a /token | Campos del formulario |
|---|---|
| Código | grant_type=authorization_code, client_id, code, code_verifier, redirect_uri, resource. |
| Renovación | grant_type=refresh_token, client_id, refresh_token, resource. Si enviás scope, debe conservar exactamente los permisos originales. |
La respuesta contiene access_token, refresh_token, token_type: Bearer, expires_in: 600 y scope. Los tokens solo sirven para el recurso MCP que autorizaste. Para cambiar los permisos, iniciá una autorización nueva.
Usar y proteger los tokens
Enviá el token de acceso en Authorization: Bearer <ACCESS_TOKEN> en cada solicitud MCP, incluida la inicialización. La cookie del login de Clasificar no autentica esas solicitudes.
El cliente debe guardar tokens y verificador de PKCE en almacenamiento seguro, separados por usuario y autorización. No los incluyas en URLs, conversaciones, analytics ni logs. Los tokens son credenciales y requieren protección.
Para verificar la conexión, inicializá el cliente y ejecutá tools/list. No uses una llamada a consultar_vehiculo o consultar_modulos como prueba: puede consumir cupo.
Renová los tokens
El cliente administra los tokens fuera de la conversación y renueva el acceso cuando vence. Estos plazos no representan una sesión de chat.
| Elemento | Duración | Qué ocurre al vencer |
|---|---|---|
| Solicitud de autorización | 10 minutos desde su creación. | Volvé a iniciar la conexión desde el asistente. Esto también aplica si el registro o la verificación del email tarda más. |
| Código de autorización | 60 segundos desde la aprobación; un solo uso. | El cliente debe reiniciar la autorización si no lo intercambia a tiempo. |
| Token de acceso | 10 minutos desde su emisión. | El cliente puede obtener otro mediante su token de renovación. |
| Token de renovación (refresh token) | 30 días desde la emisión de cada token. | Si ya no puede renovarse, es necesario autorizar otra vez. |
Cada renovación entrega un nuevo token de acceso y un nuevo refresh token. El cliente debe reemplazar el anterior y coordinar las renovaciones para no utilizarlo dos veces. Cada nuevo refresh token inicia su propio plazo de 30 días.
Reutilizar un refresh token ya consumido mientras aún no venció revoca toda esa autorización, incluidos los tokens emitidos después. Si el intercambio se interrumpe y el cliente perdió la respuesta, debe volver a autorizar en lugar de insistir con el mismo token.
Los tokens también dejan de permitir acceso si se revoca la autorización. La cuenta debe seguir habilitada para consultar y renovar. El vencimiento de un token no borra automáticamente la autorización del panel.