Odysseus AI MCP: configuracion de servidores, OAuth y solucion de problemas

Que significa MCP dentro de un espacio Odysseus

Model Context Protocol (MCP) es un protocolo para que una aplicacion de IA descubra y llame herramientas expuestas por un servidor. El servidor puede ofrecer documentos de solo lectura, consultas de calendario, busqueda o acciones como crear una tarea. El servidor define el esquema y el comportamiento de la herramienta; el host decide cuando conectarse, que mostrar y si una persona debe aprobar la llamada.

En una configuracion de Odysseus AI MCP no conviene tratar el modelo, el espacio y el proceso MCP como una sola zona de confianza. Un modelo local puede ejecutarse en tu equipo mientras un servidor MCP envia una consulta a una API alojada. Un servidor remoto puede estar fuera de tu red aunque la interfaz de Odysseus sea local. Anota ese limite antes de añadir credenciales o archivos privados.

Antes de configurar: autenticacion, admin y limites de red

La guia oficial de Odysseus situa la administracion MCP y los tokens de API dentro del area de administrador. Inicia sesion con una cuenta autorizada y comprueba que el despliegue haya cargado las mismas variables que usa el proceso de la web. Que el chat funcione en el navegador no demuestra que el proceso del servidor pueda alcanzar un endpoint MCP.

Mantén la autenticacion activa durante las pruebas. Abrir temporalmente una ruta administrativa sin login o exponer un puerto de modelo convierte un diagnostico corto en una superficie dificil de cerrar. Si Odysseus usa Docker, el callback y el nombre del servicio deben ser accesibles desde la red del contenedor, no solo desde el navegador del host. Revisa DNS, TLS, firewall y origen permitido.

Revisar servidores MCP integrados y la cache de npx

Odysseus documenta servidores MCP integrados como punto de partida. Una entrada integrada aun depende del entorno: el comando debe existir, el proceso debe arrancar con sus argumentos y la herramienta debe tener acceso a su runtime. Considera la etiqueta como un atajo de registro, no como prueba de que el servidor esta sano.

Algunos ejemplos usan un paquete npx desde una cache local. El primer arranque puede resolver un paquete y los siguientes usar la copia almacenada. Confirma que el paquete y su version estan aprobados. En un host aislado, prepara una cache autorizada o instala el comando localmente en lugar de repetir una descarga que nunca llegara al registro.

1. Elegir una entrada de bajo riesgo

   Prefiere listar un recurso de prueba o documentos de lectura. Evita shell y acceso masivo al sistema de archivos.

2. Comprobar el entorno

   Ejecuta el comando desde la misma imagen o contenedor que usa Odysseus y conserva stderr sin secretos.

3. Verificar npx

   Confirma que el paquete puede resolverse desde la cache o registro permitido y revisa la version.

npx -y @playwright/mcp@latest --help

docker compose logs --tail=120 odysseus

Añadir un servidor MCP remoto con OAuth

Un servidor remoto con OAuth añade un intercambio de identidad al transporte y al handshake de herramientas. El host de Odysseus inicia la autorizacion, el usuario concede el alcance y el proveedor devuelve el navegador al callback registrado. Ese callback debe resolver a la base publica conocida por el proveedor; un callback localhost dentro de un contenedor no sirve para un navegador remoto.

La guia de configuracion de Odysseus documenta OAUTH_REDIRECT_BASE_URL para servidores MCP remotos con OAuth. Configurala en el limite del despliegue, conserva esquema y ruta estables y reinicia el servicio que lee las variables. Nunca pegues un client secret en una pagina, prompt, captura o JSON versionado. El proveedor OAuth es la referencia para redirect y scopes.

1. Confirmar el callback

   Lee la documentacion del servidor y anota la ruta exacta, los scopes y la URL HTTPS publica.

2. Definir OAUTH_REDIRECT_BASE_URL

   Añade el valor al entorno del despliegue y reinicia el proceso que lo carga.

3. Autorizar desde Odysseus

   Inicia el flujo en Odysseus y comprueba que el navegador vuelve al host y ruta esperados.

OAUTH_REDIRECT_BASE_URL=https://mcp.example.com/oauth/callback

Seguir una prueba repetible de salud y herramientas

Usa la misma secuencia cada vez que añadas o cambies un servidor Odysseus AI MCP. Primero comprueba el espacio, despues el proceso, luego el handshake y finalmente una herramienta con una entrada conocida. Este orden separa un fallo de inferencia, transporte, permisos o proveedor en vez de esconderlo bajo un error de conexion.

Registra un resultado concreto: nombre del servidor y herramienta, forma de argumentos, estado, duracion e identificador seguro de la peticion. Elimina tokens, cabeceras, documentos privados y prompts completos. Si algo falla, conserva el esquema y una muestra redactada, no el payload privado.

1. Comprobar salud de Odysseus

   Confirma que la web y sus dependencias funcionan antes de abrir MCP.

2. Comprobar el proceso

   Revisa comando, transporte, entorno y endpoint frente a los logs.

3. Listar esquemas

   Verifica nombres, argumentos obligatorios y capacidades de lectura o escritura.

Corregir servidores inaccesibles, permisos y registros antiguos

Empieza por la capa que fallo. Si el proceso no arranca, revisa comando, paquete, directorio y entorno. Si arranca pero no muestra herramientas, revisa transporte y handshake. Si las herramientas aparecen pero fallan, comprueba argumentos, scopes OAuth, cuota y endpoint. Una respuesta que ignora la herramienta tambien puede indicar un problema del host o del modelo.

La red de contenedores causa muchos falsos fallos MCP. Un hostname que funciona en el navegador puede no resolver dentro del contenedor. Prueba el endpoint desde el mismo runtime, revisa certificados y salida de red y usa el nombre de servicio o gateway adecuado. Mantén privados los puertos de modelo y servicio salvo que la arquitectura necesite acceso externo.

Aplicar una lista practica de seguridad para tokens y red

MCP hace que las capacidades sean combinables, por lo que la configuracion mas segura es la mas pequeña que resuelve la tarea. Concede solo carpetas, dominios y acciones necesarios. Prefiere herramientas de lectura, exige aprobacion visible para escrituras y define una rotacion para OAuth y claves. Un proceso local aun puede enviar datos a un proveedor externo.

• Usa una cuenta o espacio de pruebas para la primera conexion.
• Revisa y fija comandos y versiones de paquetes.
• Guarda credenciales en el entorno o gestor de secretos.
• Limita directorios, dominios y herramientas al minimo.
• Oculta tokens, documentos privados y prompts completos en logs.