Diagnosticar una conexión MCP

Cada sección de abajo empieza con el mensaje literal que vas a ver, sea en la terminal, en el chat o en la pantalla del navegador.

«No pude conectarme al servidor»

Casi siempre es la dirección. Vitrina responde MCP en la raíz del host:

https://api.vitrinadev.com/mcp

No bajo /api/v1. Eso es un 404, y el cliente lo traduce a «servidor no disponible»:

curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.vitrinadev.com/api/v1/mcp

404

Para comprobar que escribiste bien la dirección, pídela con el navegador o con curl. Sin credencial y con GET, Vitrina se identifica:

curl https://api.vitrinadev.com/mcp

{
  "name": "vitrina",
  "version": "1.0.0",
  "transport": "streamable-http",
  "auth": "bearer-api-key"
}

Si eso responde, la dirección está bien y el problema es otro.

«Tu IA no tiene autorización»: el 401

Hay dos 401 distintos y dicen cosas distintas.

Sin credencial. Es normal, y es como empieza el flujo OAuth. Vitrina contesta con la dirección de su servidor de autorización en un header, y de ahí el cliente saca por dónde seguir:

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

Con una credencial que ya no sirve. Esto sí es un problema:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key",
    "requestId": "0aac9b83-e5e0-4f4c-88cb-b0e2b8fbe3a0"
  }
}

Ese es el mensaje exacto de una conexión revocada, y aparece en la llamada siguiente a la revocación: no hay período de gracia. Las causas, en orden de frecuencia:

1. Alguien desconectó la conexión. Mira «Aplicaciones conectadas» y «Conexiones activas» en Conexiones → MCP. Si tu conexión no está en ninguna de las dos, fue revocada y hay que autorizar de nuevo desde el cliente.
2. Pegaste la clave incompleta. Una key de conexión es sk_ y 43 caracteres. Un salto de línea o un espacio de más al copiar la convierten en otra cosa.
3. Se venció el token y no se pudo renovar. Un token OAuth dura una hora y el cliente lo renueva solo. Si la conexión fue desconectada mientras tanto, la renovación también falla:

{
  "error": "invalid_grant",
  "error_description": "refresh token invalid, expired, or reused"
}

«No encuentro esa herramienta» / el modelo dice que no puede

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

No es un error de instalación: es el perfil de conector funcionando. Un conector ve un subconjunto curado y de solo lectura; todo lo que escribe, manda mensajes o toca la configuración no existe para él. La lista completa de lo que sí puede está en Herramientas del conector.

Si lo que falta son costos, márgenes o comisiones, es otra cosa: la casilla de datos económicos. Viene desactivada, y sin ella esas seis herramientas no se registran. Para agregarlas, vuelve a autorizar marcándola, o crea una clave de conexión nueva con la casilla puesta. No se activa sobre una conexión ya existente.

«Not Acceptable» al probar con curl

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Not Acceptable: Client must accept both application/json and text/event-stream"
  },
  "id": null
}

El transporte es Streamable HTTP: una llamada tiene que declarar que acepta los dos tipos. Un cliente MCP lo hace solo; al probar a mano, hay que ponerlo:

curl -X POST https://api.vitrinadev.com/mcp \
  -H "Authorization: Bearer $VITRINA_CONNECTOR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

La respuesta llega como un evento, no como JSON pelado: una línea event: message y otra data: {…}.

«Aplicación desconocida» en la pantalla de autorización

Aplicación desconocida
unknown client_id

El cliente se presentó con una identidad que este servidor no reconoce. Pasa cuando el registro que el cliente tenía guardado se quedó obsoleto: lo hizo contra otro servidor, o contra una versión anterior de este.

En Claude Code se arregla borrando lo guardado para ese servidor y autorizando otra vez:

claude mcp logout vitrina
claude mcp login vitrina

En Cursor, un cursor-agent mcp login vitrina nuevo vuelve a registrarse solo.

«redirect_uri inválido»

redirect_uri inválido
This redirect URI is not registered for the application.

El cliente pidió que le devolvieran la autorización a una dirección que no tiene declarada. Casi nunca es algo que hayas escrito tú: son dos casos.

• Un cliente local que escucha en un puerto al vuelo. Es lo normal. Vitrina compara el redirect_uri de un cliente en localhost ignorando el puerto (RFC 8252 §7.3).
• Un cliente mal configurado, apuntando a un servidor distinto del que se registró.

Si te aparece con Claude Code o con Cursor recién instalados, logout y login de nuevo.

Te pide iniciar sesión una y otra vez

La ventana que abre tu cliente de IA usa tu navegador, así que necesita una sesión de Vitrina viva y cookies habilitadas. Abre Vitrina en ese mismo navegador, entra, y vuelve a intentarlo.

En una ventana privada, o con las cookies de terceros bloqueadas, el ciclo se repite hasta que lo permitas.

El código de autorización «ya no sirve»

{
  "error": "invalid_grant",
  "error_description": "code not found, expired, or already used"
}

Un código de autorización se canjea una vez y vive dos minutos. Si tu cliente reintentó el canje, o si volviste atrás en el navegador y repetiste la redirección, el segundo intento falla así. No se arregla reintentando: hay que empezar el flujo de nuevo.

Conectaste el workspace equivocado

La conexión se crea en el workspace que tenías activo al autorizar y no se puede mover. Desconéctala en Aplicaciones conectadas, cambia de workspace en la aplicación, y autoriza de nuevo desde el cliente.

No encuentro «Add custom connector», o el conector no aparece en el chat

El botón está al final de la lista en Personalizar → Conectores de tu cuenta (claude.ai/customize/connectors), no en la configuración del chat. Si buscaste en «Configuración», es otra pantalla. En Claude Desktop está en Settings… → Connectors; si no aparece, actualiza la aplicación.

Si ya lo agregaste y no aparece al conversar, es el otro paso: un conector se enciende por conversación, en el selector de conectores del chat.

Desconectaste una aplicación por error

No se puede deshacer: los permisos se revocan en el momento y la cadena de renovación se quema. Vuelve a agregar el conector en tu cliente y autorízalo de nuevo. La casilla de costos y márgenes vuelve a aparecer desactivada, así que márcala otra vez si la necesitabas.

Nada de lo anterior

Cada error de la API trae un requestId. Mándanoslo tal cual: es lo que nos deja encontrar esa llamada exacta en los registros.