Servidor MCP (Claude y asistentes de IA)

Es un puente seguro entre los datos de su bodega y un cliente compatible con MCP. Tras autenticarse, el asistente puede invocar herramientas de VinoCellar en su nombre, según su suscripción y las reglas de la cuenta.

La URL pública exacta aparece en la app VinoCellar, pantalla MCP / tokens (ruta interna /app/mcp), bloque «Dirección del servidor MCP». Cópiela tal cual.

En la app de producción pública de VinoCellar, el host MCP predeterminado es https://mcp.vinocellar.app . Prefiera siempre el valor mostrado en la app si difiere (compilaciones personalizadas o configuración futura mediante EXPO_PUBLIC_MCP_SERVER_URL).

1. Abra la app → sección MCP (o Ajustes → VinoCellar MCP → gestionar tokens).
2. Copie la URL del servidor en el bloque indicado.
3. En Claude Desktop (u otro cliente), añada un servidor MCP y pegue la URL según la documentación actual del cliente.
4. En el primer enlace, complete el paso OAuth en el navegador; pegue el token personal creado en la app cuando se lo pida el formulario.

El servidor MCP de VinoCellar sigue la especificación MCP con transporte Streamable HTTP: su cliente se comunica con el punto de entrada MCP por HTTPS (no es un catálogo REST genérico para explorar a mano).

En la primera conexión, el cliente MCP inicia un flujo tipo OAuth. Una ventana del navegador le pedirá pegar el token de acceso personal creado en la app VinoCellar; el servidor MCP lo valida con la API de VinoCellar y luego entrega credenciales que el cliente envía como token Bearer en las peticiones MCP posteriores.

Los tokens creados desde la pantalla MCP se emiten con los ámbitos mcp:read y mcp:write para que el asistente pueda invocar las herramientas registradas por VinoCellar.

Para comprobar de forma sencilla que el host responde (sin sesión MCP completa), el servidor contesta a GET /ping con el texto plano pong.

El token identifica su cuenta ante el servidor MCP:

1. En la app, abra la pantalla MCP y cree un token.
2. Asígnele una etiqueta clara (p. ej. «MacBook», « Claude Desktop », «Cursor»).
3. Copie el valor de inmediato: solo se muestra una vez.
4. Revogue un token en la misma pantalla si pierde un dispositivo o quiere desconectar un cliente.

Trate los tokens como contraseñas: quien tenga el token y la URL puede acceder a su bodega vía MCP hasta que lo revoque.

Estos son los nombres exactos de herramienta expuestos a los clientes MCP:

• vinocellar_whoami — verificar la cuenta vinculada; la respuesta JSON incluye un objeto mcp (texto de bienvenida, URL de FAQ, pistas de herramientas).
• vinocellar_help — devuelve el mismo JSON de bienvenida que el objeto mcp de vinocellar_whoami sin volver a llamar a la API de perfil.
• vinocellar_list_wines — inventario amplio; prefiera vinocellar_search_wines para filtrar por nombre o dominio.
• vinocellar_search_wines — búsqueda de texto en sus botellas.
• vinocellar_get_caves — listar bodegas físicas antes de elegir una.
• vinocellar_get_cave — disposición por casilleros; proporciona log_id para vinocellar_move_bottle.
• vinocellar_move_bottle — mover una botella a otro casillero u otra bodega usando el log_id devuelto por vinocellar_get_cave.
• vinocellar_import_wine — añadir un vino desde wine_data estructurado (forma GeminiWineResponse) e imágenes opcionales de etiqueta delantera/trasera en base64; requiere suscripción MCP activa en la cuenta.

Las herramientas MCP se limitan a las operaciones de inventario y bodega enumeradas arriba.

El asistente Vino en la app, el asistente maridaje, el diario de cata y otras funciones de IA no se exponen como herramientas MCP independientes — use la app móvil o la web para esos casos.

VinoCellar está pensado para personas que usan un cliente MCP compatible (p. ej. Claude Desktop): copia la URL del servidor desde la app y crea un token personal.

No hay una aplicación OAuth de terceros separada ni documentación OpenAPI «MCP como REST»: el contrato es el protocolo MCP (tools/list y la descripción/esquema de cada herramienta tal como la muestra su cliente).

Los créditos se usan sobre todo para escaneos de etiquetas en la app. La suscripción MCP es aparte: mientras esté activa, las llamadas al servidor MCP para las operaciones admitidas no están limitadas por su saldo de créditos de escaneo del mismo modo.

Claude Desktop y los clientes compatibles con MCP con el transporte de VinoCellar están soportados hoy. Se prevé compatibilidad con ChatGPT y Gemini; consulte las notas de versión y esta FAQ.