Conectar tu IA a Vitrina

Vitrina habla MCP (Model Context Protocol) en una sola dirección:

https://api.vitrinadev.com/mcp

Pegas esa dirección en Claude, en Claude Code o en Cursor, y autorizas una vez. Desde ahí tu asistente responde con los datos de tu workspace: los leads sin contestar, la agenda de la semana, el catálogo.

Qué ve, y qué no

La conexión nace de solo lectura y acotada. No es tu API key: es un perfil distinto, con menos herramientas y ninguna que escriba.

Tu IA puede leer conversaciones, contactos, leads y tickets; las métricas de atención y de tus agentes de IA; la agenda y las citas; y tu catálogo. La lista exacta está en Herramientas del conector, generada desde el catálogo real. Incluye las herramientas propias de tu rubro, y solo las de tu rubro.

A esas se suman tres herramientas genéricas: search_operations, describe_operation y call_operation. Alcanzan cualquier operación publicada de la API, con tu misma credencial y tus mismos permisos. Qué llegan a tocar y qué no, en Llamar la API completa desde tu IA.

Escribir se autoriza por área

En la pantalla de autorización, debajo del acceso de lectura, aparecen los «Permisos de escritura (opcional)». Hay una línea por área, cada una con un interruptor apagado: Contactos, Leads, Casos, Conversaciones, Agenda, Catálogo y Mensajes a clientes. Si no tocas ninguno, la conexión no puede cambiar nada.

Cada interruptor está limitado dos veces: la aplicación tiene que haberlo pedido, y tu rol tiene que incluirlo. Un área que tu rol no permite aparece deshabilitada. Si la autorizas igual, la respuesta es un error que nombra el permiso que falta. La credencial sigue siendo tuya, así que un rol más angosto angosta la conexión en su llamada siguiente.

Lo que nunca es un área que puedas autorizar: crear o revocar credenciales, los webhooks, la configuración del workspace y la forma de tus embudos. Lo que la especificación marca como sensible queda fuera de MCP con cualquier permiso, sea cual sea el rubro del workspace. Ver Datos personales y de salud.

Cuando autorizas «Mensajes a clientes», escribirle a un contacto a la vez sale directo. A partir del cuarto contacto distinto en diez minutos, el mensaje queda esperando que alguien del equipo lo apruebe en Seguimientos → Aprobaciones. Ver Enviar mensajes.

Una herramienta que hace algo que no autorizaste no existe para esa conexión. Eso no es una promesa de comportamiento del modelo: no aparece en la lista, y una llamada a una de ellas responde que no existe.

{
  "content": [
    { "type": "text", "text": "MCP error -32602: Tool tenant_settings_update not found" }
  ],
  "isError": true
}

Es la respuesta a tenant_settings_update, una herramienta que existe en el catálogo completo de la API, pedida con una credencial de conector.

Las dos formas de autorizar

Las dos terminan en lo mismo: una credencial acotada al perfil de conector. La primera no te hace manipular un secreto, caduca sola cada hora y se renueva sin que hagas nada. La segunda es un string que tú guardas.

Las dos se crean y se revocan en Conexiones → MCP, en la aplicación. Ahí conviven dos tablas que no son lo mismo: «Conexiones activas» son las claves, «Aplicaciones conectadas» son las autorizaciones OAuth.

Costos, márgenes y comisiones

Es la única decisión que tomas al conectar, y viene desactivada.

Marcada, tu IA puede además responder sobre lo que pagaste por cada unidad, el margen de cada negocio y las comisiones de tu equipo. Sin marcar, esas herramientas no existen para el conector. El modelo no las ve, así que no gasta un turno intentándolo ni te cuenta que hay un informe que no puede abrir.

En el flujo OAuth la casilla está en la pantalla de permisos. Con una clave de conexión, está al crearla.

Qué ve tu IA de una persona

Depende del rubro del workspace: hay uno donde la identidad viaja recortada por defecto.

Una conexión, un workspace

La credencial nace pegada al workspace en el que estabas al autorizar, igual que una key sk_ (ver Autenticación). No hay parámetro de workspace en ninguna llamada, y no se puede mover a otro. Si administras dos workspaces, son dos conexiones.

La pantalla de permisos lo dice antes de que decidas:

La conexión se creará en el workspace que tienes activo. Si querías otro, cámbialo antes de continuar.

Ve lo que ves tú

Una aplicación conectada actúa como la persona que la autorizó, en ese workspace. Ve exactamente lo que esa persona ve en Vitrina, y eso se resuelve otra vez en cada llamada. Si un admin te cambia el rol, o te deja la Visibilidad de registros en «Solo asignados», la siguiente pregunta que le hagas a tu IA ya responde con esa vista. Lo mismo con la Visibilidad de stock en «Solo sus sucursales». Lo que aceptaste al conectar es un techo, nunca más de lo que tu rol permite hoy. Si tu membresía termina o queda suspendida, la conexión responde 401 desde la llamada siguiente, aunque nadie la haya revocado.

Cómo lo descubre tu cliente

No hace falta que sepas esto para conectar, pero explica lo que ves si miras el tráfico.

Una llamada sin credencial responde 401 con la dirección de su propio servidor de autorización en un header. Con eso un cliente MCP empieza el flujo solo:

HTTP/2 401
www-authenticate: Bearer resource_metadata="https://api.vitrinadev.com/.well-known/oauth-protected-resource/mcp"
access-control-expose-headers: WWW-Authenticate
content-type: application/json; charset=utf-8

{"error":{"code":"UNAUTHORIZED","message":"Missing bearer token","requestId":"1e186199-a51c-4987-8e33-ba8971c51fa5"}}

De ahí el cliente lee los dos documentos de descubrimiento:

curl https://api.vitrinadev.com/.well-known/oauth-protected-resource

{
  "resource": "https://api.vitrinadev.com/mcp",
  "authorization_servers": ["https://api.vitrinadev.com"],
  "scopes_supported": ["mcp:connector", "dealership_economics:read"],
  "bearer_methods_supported": ["header"]
}

curl https://api.vitrinadev.com/.well-known/oauth-authorization-server

{
  "issuer": "https://api.vitrinadev.com",
  "authorization_endpoint": "https://api.vitrinadev.com/oauth/authorize",
  "token_endpoint": "https://api.vitrinadev.com/oauth/token",
  "registration_endpoint": "https://api.vitrinadev.com/oauth/register",
  "revocation_endpoint": "https://api.vitrinadev.com/oauth/revoke",
  "scopes_supported": ["mcp:connector", "dealership_economics:read"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "revocation_endpoint_auth_methods_supported": ["none"]
}

Un cliente se registra solo (POST /oauth/register, registro dinámico) o se identifica con la URL de su propio documento de metadatos. Claude Code hace lo segundo. En los dos casos hay PKCE S256 y no hay secreto de cliente: token_endpoint_auth_methods_supported es ["none"].

El token que sale al final dura una hora y trae con qué renovarse:

{
  "access_token": "sk_TOfO-agV…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_ojdAa_Fo…",
  "scope": "mcp:connector dealership_economics:read"
}

El access_token es una key sk_: una autorización OAuth y una clave de conexión son la misma credencial por dentro, y por eso llegan al mismo perfil de herramientas. Lo que cambia es quién la guarda y quién la renueva.

Sigue por tu cliente