Servidor MCP — Guía del Usuario

¿Qué es?

El servidor MCP (Model Context Protocol) para meni.ge permite conectar asistentes de IA (Claude, ChatGPT, Cursor, VS Code Copilot, etc.) a los datos de tu restaurante. La IA obtiene acceso al menú, ubicaciones, pedidos, imágenes y puede gestionarlos en tu nombre.

Inicio Rápido

1. Obtén una clave API

La clave API se genera en el panel de administración de tu restaurante.

Paso a paso:

Inicia sesión en el Panel de Administración en admin.meni.ge
En el menú lateral, abre ⚙️ Configuración → 🔑 Acceso
En la página, encuentra la sección 🤖 Claves API MCP
Haz clic en el botón «Generar nueva clave»
Introduce un nombre para la clave (por ejemplo, «Claude Desktop», «Cursor», «Mi GPT») — esto ayudará a distinguir las claves entre sí
Copia la clave inmediatamente — se muestra solo una vez.

💡 En esta misma página se muestra la URL del servidor (https://api.meni.ge/mcp), que también puedes copiar con un clic.

Gestión de claves

Puedes crear hasta 10 claves por cuenta
Cada clave puede ser revocada en cualquier momento — botón «Revocar» junto a la clave
Después de revocar, la clave deja de funcionar inmediatamente
Si pierdes la clave — revócala y crea una nueva

2. Conecta el asistente de IA

Claude Desktop / Claude Code

Archivo de configuración claude_desktop_config.json:

{
  "mcpServers": {
    "meni": {
      "url": "https://api.meni.ge/mcp",
      "headers": {
        "Authorization": "Bearer TU_CLAVE_API"
      }
    }
  }
}

Cursor

En la configuración de Cursor → MCP Servers → Add, o archivo .cursor/mcp.json:

{
  "mcpServers": {
    "meni": {
      "url": "https://api.meni.ge/mcp",
      "headers": {
        "Authorization": "Bearer TU_CLAVE_API"
      }
    }
  }
}

VS Code (GitHub Copilot)

En el proyecto .vscode/mcp.json:

{
  "servers": {
    "meni": {
      "type": "http",
      "url": "https://api.meni.ge/mcp",
      "headers": {
        "Authorization": "Bearer TU_CLAVE_API"
      }
    }
  }
}

Otras herramientas de IA

Instrucciones detalladas paso a paso para Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Continue, ChatGPT y otros — en una guía separada:

👉 Conexión de herramientas de IA a MCP

¿Qué puede hacer el asistente de IA?

Para propietarios de restaurantes (usuarios comunes)

Comando	Descripción
`whoami`	Mostrar datos de la cuenta (userId, email, rol)
`my_profile`	Obtener tu perfil de usuario
`update_my_profile`	Actualizar campos en tu perfil
`my_locations`	Lista de todas tus ubicaciones
`my_orders`	Lista de tus pedidos
`my_images`	Lista de tus imágenes (menú, categorías, ubicaciones)

Perfiles de usuarios

Comando	Descripción
`get_user_profile`	Obtener perfil de usuario por userId
`update_user_profile`	Actualizar campos del perfil de usuario
`list_users`	`[ADMIN]` Lista de todos los usuarios
`search_user_by_email`	`[ADMIN]` Buscar usuario por email a través de Cognito

Gestión de ubicaciones

Comando	Descripción
`list_locations`	Todas las ubicaciones del usuario
`get_location_profile`	Perfil de la ubicación (nombre, dirección, horario, configuraciones)
`update_location_profile`	Actualizar configuraciones de la ubicación (se sincroniza automáticamente con CDN)
`get_location_menu`	Menú completo de la ubicación con categorías y posiciones

Gestión del menú

Comando	Descripción
`list_menu_items`	Todas las posiciones del menú (con categoryId — datos completos, sin — pares item/category ID)
`get_menu_item`	Obtener posición con datos completos (incluyendo traducciones, variantes, añadidos)
`update_menu_item`	Actualizar posición del menú (precio, descripción, estado, etiquetas, variantes, añadidos)
`create_menu_item`	Crear nueva posición de menú en una categoría
`create_menu_category`	Crear nueva categoría de menú
`update_menu_category`	Actualizar categoría (nombre, traducciones, estado, orden de clasificación)
`move_menu_item`	Mover posición de una categoría a otra
`merge_categories`	Fusionar dos categorías (todas las posiciones se trasladan, la original se elimina)
`delete_menu_category`	Eliminar categoría (con `force: true` — junto con todas las posiciones)

Pedidos

Comando	Descripción
`list_orders`	Lista de pedidos (por userId o dominio)
`get_order`	Detalles de un pedido específico

Dominios

Comando	Descripción
`check_domain_availability`	Verificar disponibilidad de un nombre de dominio
`set_location_domain`	Cambiar el nombre de dominio de la ubicación (actualiza CDN y mapeos)
`resolve_domain`	Obtener userId y locationId por dominio
`list_domains`	`[ADMIN]` Lista de todos los dominios registrados

CDN (datos publicados)

Comando	Descripción
`get_cdn_profile`	Perfil publicado de la ubicación (en CDN)
`get_cdn_menu`	Menú publicado en el idioma especificado
`list_cdn_files`	Todos los archivos publicados del dominio
`invalidate_cdn_cache`	`[ADMIN]` Invalidar caché de CloudFront CDN

Imágenes

Comando	Descripción
`list_user_images`	Todas las imágenes del usuario
`get_image_upload_url`	Obtener URL presignada para subir imagen a S3 (JPEG/PNG/WebP)
`delete_image`	Eliminar imagen (usuarios — solo las suyas)

Acceso de bajo nivel a S3

Comando	Descripción
`s3_read`	Leer archivo de S3 (usuarios — solo los suyos)
`s3_write`	`[ADMIN]` Escribir datos JSON en S3
`s3_list`	Lista de archivos en S3 (usuarios — solo su prefijo)
`s3_delete`	`[ADMIN]` Eliminar objeto de S3

Cognito

Comando	Descripción
`cognito_list_users`	`[ADMIN]` Lista de usuarios del Cognito User Pool
`cognito_get_user`	`[ADMIN]` Información detallada de un usuario de Cognito

Estadísticas

Comando	Descripción
`get_system_stats`	`[ADMIN]` Estadísticas del sistema

Autenticación

El servidor soporta tres métodos de autorización:

1. Clave API (recomendada para asistentes de IA)

Authorization: Bearer tu_clave_de_64_caracteres

La clave se genera en el panel de administración. Está vinculada a tu cuenta — la IA solo ve tus datos.

2. Token JWT de Cognito

Para integración programática, puedes obtener un token a través de login:

# Obtener token
curl -X POST https://api.meni.ge/mcp/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "tu@email.com", "password": "tu_contraseña"}'

# La respuesta contiene idToken — úsalo:
Authorization: Bearer eyJraWQ...

El token es válido por 1 hora, después de lo cual se requiere un nuevo inicio de sesión.

3. Clave API de Administrador (solo para administradores)

Authorization: Bearer admin_key

La clave de administrador da acceso completo a todos los datos de todos los usuarios.

Seguridad

Cada clave API está vinculada a una cuenta específica
Los usuarios comunes ven solo sus datos
La clave puede ser revocada en cualquier momento en el panel de administración
Máximo 10 claves por cuenta
Todas las solicitudes se realizan a través de HTTPS
Los comandos marcados con [ADMIN] no están disponibles para usuarios comunes

Ejemplos de uso

Pedir a la IA que actualice el precio de un plato

«Actualiza el precio del plato «Khachapuri» en mi menú — ponlo a 15 lari en lugar de 12»

La IA llamará a my_locations → get_location_menu → update_menu_item.

Añadir una nueva posición al menú

«Añade en la categoría «Postres» un nuevo plato «Churchkhela» por 8 lari»

La IA llamará a my_locations → get_location_menu → create_menu_item.

Crear una nueva categoría

«Crea la categoría «Bebidas» con traducciones al georgiano e inglés»

La IA llamará a create_menu_category con nameTranslations.

Mover un plato entre categorías

«Mueve «Limonada» de «Bebidas frías» a «Sin alcohol»»

La IA llamará a move_menu_item indicando la categoría de origen y destino.

Ver pedidos de hoy

«Muestra mis pedidos de hoy»

La IA llamará a my_orders y filtrará por fecha.

Verificar el menú publicado

«¿Cómo se ve mi menú en ruso para los visitantes?»

La IA llamará a resolve_domain → get_cdn_menu con el idioma ru.

Cambiar el dominio del restaurante

«Verifica si el dominio my-restaurant está disponible, y si es así — establécelo»

La IA llamará a check_domain_availability → set_location_domain.

Subir foto de un plato

«Dame un enlace para subir la foto del plato X»

La IA llamará a get_image_upload_url y devolverá la URL presignada para subir.

Endpoints de la API

Método	URL	Descripción
`GET`	`https://api.meni.ge/mcp`	Información del servidor + lista de herramientas
`POST`	`https://api.meni.ge/mcp`	MCP JSON-RPC (protocolo principal)
`GET`	`https://api.meni.ge/mcp/health`	Verificación de estado
`POST`	`https://api.meni.ge/mcp/auth/login`	Login → Tokens JWT
`GET`	`https://api.meni.ge/mcp/api/keys`	Lista de tus claves API
`POST`	`https://api.meni.ge/mcp/api/keys`	Crear nueva clave API
`DELETE`	`https://api.meni.ge/mcp/api/keys/{id}`	Revocar clave API

Gestión de claves

Ver claves

En el panel de administración → Configuración → Acceso → Claves API MCP. O a través de la API:

curl https://api.meni.ge/mcp/api/keys \
  -H "Authorization: Bearer COGNITO_JWT_TOKEN"

Crear clave

curl -X POST https://api.meni.ge/mcp/api/keys \
  -H "Authorization: Bearer COGNITO_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Claude Desktop"}'

La respuesta contiene el campo key — esa es tu clave. Guárdala!

Revocar clave

curl -X DELETE https://api.meni.ge/mcp/api/keys/mk_abc123 \
  -H "Authorization: Bearer COGNITO_JWT_TOKEN"

⚠️ Crear y revocar claves requiere un token JWT de Cognito (no una clave API). Usa el panel de administración — es más fácil.

Solución de problemas

Problema	Solución
`401 Unauthorized`	Verifica la clave API. Si está revocada — crea una nueva
`403 user identity required`	Usa JWT de Cognito para gestionar claves
`🔒 admin access required`	El comando está disponible solo para administradores
`🔒 access denied`	Estás intentando acceder a datos de otro usuario
La clave no funciona	Verifica que la clave no haya sido revocada, y el formato: `Bearer <clave>`