MCP
La misma clave de API, expuesta a un agente de IA como una herramienta tipada por cada método permitido.
Xuda ejecuta un servidor de Model Context Protocol en /mcp, junto a /cpi. Conecta un agente compatible con MCP
a él, iniciando sesión o con una clave de API, y cada método que esa clave puede llamar aparece como una
herramienta tipada, sin una integración aparte que tengan que escribir los agentes de IA.
Conectar
Hay dos formas de entrar, y ambas terminan en el mismo lugar: los derechos de una clave de API.
Iniciar sesión (conectores de Claude y otros clientes OAuth)
Añade https://xuda.ai/mcp como conector personalizado en Claude (Configuración, Conectores, Añadir
conector personalizado), deja vacíos el ID y el secreto de cliente OAuth y pulsa Conectar. Claude abre
Xuda: inicia sesión si aún no lo has hecho, y una ventana del panel te pregunta con cuál de tus claves de API actúa
la conexión; elige una y pulsa Conectar. Claude en la web, Desktop, móvil y Cowork
comparten esa conexión, y cualquier otra cuenta de Claude la añade del mismo modo. La pestaña
Desarrolladores, MCP del panel muestra la dirección que hay que pegar, estos pasos y todo lo que sigue.
Claude Code inicia sesión de la misma manera cuando añades el servidor sin cabecera, luego ejecuta /mcp y
elige Authenticate:
La conexión nunca tiene derechos propios. Cada llamada a una herramienta se ejecuta como la clave que elegiste, así que el modo de acceso de la clave, su lista de permitidos y su revocación son también los de la conexión: revoca la clave en Desarrolladores, API keys y la conexión se detiene, y el siguiente inicio de sesión pedirá otra clave. La página lista solo tus propias claves activas; si no tienes ninguna, crea una primero.
Para quienes desarrollan clientes, el servidor sigue la especificación de autorización de MCP:
Una llamada a /mcp sin un token utilizable responde 401 con WWW-Authenticate: Bearer resource_metadata="...", que es como un cliente encuentra el resto. Los tokens de acceso duran una hora; los tokens
de actualización duran 90 días y se reemplazan en cada uso. Un URI de redirección de loopback (http://localhost o
http://127.0.0.1) coincide en cualquier puerto.
Una clave de API en una cabecera
La clave va en una cabecera Authorization: Bearer, la misma clave que usarías como api_key en
/cpi. No hay una credencial MCP aparte. Una solicitud sin cabecera Authorization, o con una clave
que no corresponde a un documento xuda_api_keys activo, se rechaza con 401 antes de que se registre
ninguna herramienta.
Sesiones
El transporte es HTTP en streaming: la primera solicitud es una llamada MCP initialize, que abre una
sesión y devuelve una cabecera mcp-session-id; cada solicitud siguiente en esa conexión lleva
la misma cabecera y la misma credencial. Una sesión se cierra tras 10 minutos sin solicitudes. Una
solicitud en una sesión cerrada responde 404, y entonces un cliente MCP inicia una nueva sesión por
su cuenta.
Qué se convierte en herramienta
Las herramientas se registran al inicio de la sesión a partir del mismo modo de acceso que ya tiene la clave:
- Acceso total: cada método del catálogo que no sea
privatese registra como una herramienta, resuelto en el momento de la conexión, así que un método añadido después de crear la clave está disponible sin cambiar la propia clave. - Acceso personalizado: solo se registran los métodos de la lista de permitidos de la clave.
Una sesión en marcha se mantiene al día con su clave: revisa la clave cada minuto, y los módulos y
plugins que hay detrás cada cinco, y cuando el conjunto de herramientas ha cambiado envía
notifications/tools/list_changed. Un cliente que escucha (Claude lo hace) lee la nueva lista sin
reconectar, así que un método que permites en la clave llega a un agente que ya está conectado.
Cada herramienta conserva la forma del método: el nombre de la herramienta es el nombre del método (get_account_projects,
dbs_read, ...), su título es el nombre del método en Title Case, su descripción es la propia
description del método, y su esquema de entrada se construye campo a campo a partir de los fields del método; los campos
obligatorios siguen siendo obligatorios, todo lo demás es opcional. Un campo sin un tipo reconocido sigue convirtiéndose en un
argumento de herramienta permisivo en lugar de romper toda la sesión, así que un método mal especificado
nunca arrastra consigo al resto del catálogo.
Una clave limitada a un Full Stack VPS también expone las herramientas de los plugins instalados en esa máquina junto a los métodos del ecosistema anteriores, de modo que un agente puede llegar tanto a la plataforma como a lo que la persona desarrolladora construyó en la máquina en una sola sesión. Consulta Full Stack VPS.
Llamar a una herramienta
Un agente llama a una herramienta con los mismos argumentos que describen los campos del método. Xuda responde
llamando internamente al método, igual que lo haría /cpi/<method>, y devuelve a la herramienta el sobre
{code, data} del método como texto. Una llamada fallida sigue devolviéndose con normalidad en la capa MCP; el código
-1 y los demás aparecen en el resultado de la herramienta exactamente como en una llamada REST normal, así que un agente lo lee
igual que lo haría tu propio manejo de errores. Consulta Errores.
Una solicitud que falla antes de que se ejecute ninguna herramienta, una credencial ausente o rechazada (401), una sesión
que se ha cerrado (404, código -32001), un mensaje MCP mal formado, vuelve como un error JSON-RPC
en lugar de un resultado de herramienta: