Empezar con un ejemplo en ejecución
Lánzalo y adáptalo a tu proyecto
Crea la API Orders, una base PostgreSQL y el servidor MCP que elijas en Adios. Subimos el código, configuramos credenciales JWT independientes e iniciamos las vistas previas de desarrollo.
Lanzar en Adios →¿Aún no tienes cuenta? Crea una y vuelve a este ejemplo. Selecciona un equipo y revisa los recursos antes de lanzarlo. El ejemplo completo requiere un plan de pago con capacidad para dos espacios y una base de datos.
Créalo paso a paso
Seguir la guía manual
Diseña la API y el esquema, añade autenticación JWT, escribe las herramientas MCP y ejecútalas en tus espacios de desarrollo. Cada paso incluye código y comandos.
Seguir los pasos manuales →Explora primero el ejemplo en ejecución. OAuth para el acceso de usuarios y el despliegue en producción son pasos posteriores.
Diseña la API para un caso de uso real
Empieza por definir para qué sirve la API. Nuestro ejemplo permite que un panel interno, un asistente de soporte y una automatización consulten el estado de envío de un pedido. Todos usan la misma operación de negocio. La API controla los datos y las reglas de acceso; MCP permite a un cliente de IA descubrir y llamar esa operación.
Define la primera versión como solo lectura: un solicitante autorizado proporciona un ID de pedido y recibe su ID y estado de envío. No incluyas direcciones, datos de pago ni notas internas en esta respuesta. Crear pedidos, emitir reembolsos y modificar envíos requiere endpoints y permisos separados.
- ¿Quién llama a la API? Un usuario o servicio conocido con un tenant asignado.
- ¿Qué puede hacer? Leer pedidos de ese tenant con el permiso orders:read.
- ¿De qué se encarga la API? Validar la solicitud, verificar al solicitante, comprobar la pertenencia y devolver una respuesta estable.
- ¿De qué se encarga MCP? Describir una herramienta específica, validar su entrada y llamar a la API con la identidad verificada del solicitante.
Escribe este contrato antes de elegir un SDK. Mantiene el sitio, las integraciones y las herramientas de IA bajo el mismo modelo de permisos, en lugar de dar al cliente de IA acceso directo a la base de datos.
Diseña el esquema y las reglas de pertenencia
Usa PostgreSQL para este ejemplo. Un tenant representa una tienda u organización. Una identidad vincula el sujeto de un token verificado con un tenant y puede desactivarse. Cada pedido pertenece a un tenant. La API usa esa relación para decidir si el solicitante puede consultarlo.
| Tabla | Propósito | Regla de acceso |
|---|---|---|
tenants | Poseer los datos de la organización | Referenciado por identidades y pedidos |
principals | Asociar un sujeto verificado con un tenant | Solo las identidades activas pueden leer datos |
orders | Guardar el estado de envío | El tenant del solicitante debe coincidir con el del pedido |
-- Demo bootstrap only. Use versioned migrations for an existing production DB.
CREATE TABLE IF NOT EXISTS tenants (
id uuid PRIMARY KEY,
name text NOT NULL
);
CREATE TABLE IF NOT EXISTS principals (
subject text PRIMARY KEY,
tenant_id uuid NOT NULL REFERENCES tenants(id),
active boolean NOT NULL DEFAULT true
);
CREATE TABLE IF NOT EXISTS orders (
tenant_id uuid NOT NULL REFERENCES tenants(id),
id varchar(64) NOT NULL CHECK (id ~ '^[A-Za-z0-9-]{1,64}$'),
status text NOT NULL CHECK (status IN ('pending', 'shipped', 'delivered')),
created_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (tenant_id, id)
);
-- Fictional data; ownership comes from the verified subject, not tool input.
INSERT INTO tenants (id, name) VALUES
('11111111-1111-4111-8111-111111111111', 'Demo shop'),
('22222222-2222-4222-8222-222222222222', 'Other shop')
ON CONFLICT DO NOTHING;
INSERT INTO principals (subject, tenant_id) VALUES
('demo-client', '11111111-1111-4111-8111-111111111111'),
('other-client', '22222222-2222-4222-8222-222222222222')
ON CONFLICT DO NOTHING;
INSERT INTO orders (tenant_id, id, status) VALUES
('11111111-1111-4111-8111-111111111111', 'demo-1001', 'shipped'),
('22222222-2222-4222-8222-222222222222', 'other-1002', 'pending')
ON CONFLICT DO NOTHING;La clave compuesta permite el mismo ID de pedido en distintos tenants. Las claves externas evitan registros huérfanos y la restricción de estado impide valores no admitidos. La consulta une el sujeto verificado con su tenant y el pedido; el solicitante no puede elegir un tenant en la entrada de la herramienta.
La inicialización incluye dos tenants ficticios para probar el aislamiento: demo-client puede leer demo-1001, mientras que other-client posee other-1002. La demo ejecuta una inicialización idempotente al arrancar. Para una base de producción existente, usa migraciones versionadas y separa el aprovisionamiento de las solicitudes de la aplicación.
Define endpoints, respuestas y autenticación JWT
La API pública ofrece un endpoint de consulta de pedidos. Una respuesta correcta es un objeto JSON pequeño con id y status. Mantén estable el esquema para que el sitio y la herramienta MCP puedan usarlo con confianza.
GET /orders/demo-1001
Authorization: Bearer <API-audience JWT>
200 { "id": "demo-1001", "status": "shipped" }
401 missing, invalid or expired JWT
403 valid JWT without orders:read
404 unknown order, inactive identity or another tenant’s order
503 database unavailableLa autenticación JWT es el mínimo en todas las implementaciones siguientes. La cabecera bearer transporta el token; no basta con compararlo con una cadena aleatoria ni con decodificarlo. Verifica su firma con un algoritmo permitido, exige el emisor y la audiencia previstos, comprueba caducidad y sujeto y aplica el scope antes de acceder a la base de datos.
{
"iss": "orders-demo",
"aud": "orders-mcp",
"sub": "demo-client",
"scope": "orders:read",
"iat": 1791498000,
"exp": 1791498900
}La demo controlada usa HS256 con secretos de firma separados para API y MCP. Un script exclusivo del operador emite un JWT MCP de corta duración. El servidor lo verifica y firma un JWT nuevo de cinco minutos para la audiencia orders-api con el mismo sujeto verificado. La API verifica ese segundo token y consulta el tenant del sujeto en PostgreSQL.
Esto convierte MCP en un gateway de confianza con autoridad para firmar tokens de la API. Nunca entregues secretos de firma a clientes ni expongas el emisor de tokens como endpoint público. Fuera de este ámbito de confianza, usa preferiblemente un proveedor OAuth que emita JWT asimétricos y verifica sus claves públicas; la sección OAuth muestra el servidor de recursos. JWT es un formato de token; OAuth gestiona la autorización delegada y el inicio de sesión.
No aceptes un ID de tenant del cliente como prueba de pertenencia. No reenvíes un token con audiencia MCP a la API. Usa tokens breves, rota claves y emplea HTTPS en producción. Con varios proveedores de identidad, asocia la pareja emisor y sujeto a una identidad canónica en lugar de asumir que los sujetos son únicos globalmente.
Emisor JWT de demo exclusivo del operador
import { createHmac } from "node:crypto";
// Operator-only demo issuer. Never expose this script or its key to end users.
const audience = process.argv[2] || "orders-mcp";
if (!["orders-mcp", "orders-api"].includes(audience))
throw new Error("Unknown audience");
const secret =
process.env[audience === "orders-api" ? "API_JWT_SECRET" : "MCP_JWT_SECRET"];
if (!secret || secret.length < 32)
throw new Error("Set the audience's JWT signing secret");
const encode = (value) =>
Buffer.from(JSON.stringify(value)).toString("base64url");
const now = Math.floor(Date.now() / 1000);
const data = `${encode({ alg: "HS256", typ: "JWT" })}.${encode({ iss: "orders-demo", aud: audience, sub: "demo-client", scope: "orders:read", iat: now, exp: now + 900 })}`;
process.stdout.write(
`${data}.${createHmac("sha256", secret).update(data).digest("base64url")}`,
);Implementa la API antes de añadir MCP
Descomprime los ejemplos y abre api/. La implementación Node.js usa jose para verificar JWT y pg para consultar PostgreSQL. Instala las dependencias fijadas con npm ci. La consulta parametrizada une el sujeto verificado con su tenant y devuelve solo pedidos de ese tenant.
Dependencias de la API y comando de inicio
{
"name": "orders-api",
"private": true,
"type": "module",
"scripts": {
"start": "node init-db.mjs && node server.mjs"
},
"dependencies": {
"jose": "^6.1.0",
"pg": "8.23.1"
}
}import http from "node:http";
import { jwtVerify } from "jose";
import pg from "pg";
const secret = process.env.API_JWT_SECRET;
if (!secret || secret.length < 32 || !process.env.DATABASE_URL) {
throw new Error(
"Set DATABASE_URL and an API_JWT_SECRET of at least 32 characters",
);
}
const key = new TextEncoder().encode(secret);
const pool = new pg.Pool({
connectionString: process.env.DATABASE_URL,
max: 5,
connectionTimeoutMillis: 5000,
statement_timeout: 5000,
});
pool.on("error", () => console.error("Database connection failed"));
await pool.query("SELECT 1");
const server = http.createServer(async (req, res) => {
const send = (status, data) => {
res.writeHead(status, {
"Content-Type": "application/json",
"Cache-Control": "no-store",
});
res.end(JSON.stringify(data));
};
if (req.url === "/healthz" && req.method === "GET") {
try {
await pool.query("SELECT 1");
return send(200, { ok: true });
} catch {
return send(503, { ok: false });
}
}
let principal;
try {
const match = /^Bearer (\S+)$/.exec(req.headers[(process.env.API_AUTH_HEADER || "Authorization").toLowerCase()] || "");
if (!match) throw new Error("Missing access token");
const { payload } = await jwtVerify(match[1], key, {
issuer: "orders-demo",
audience: "orders-api",
algorithms: ["HS256"],
requiredClaims: ["sub", "exp"],
});
if (typeof payload.sub !== "string" || !payload.sub)
throw new Error("Missing subject");
if (
typeof payload.scope !== "string" ||
!payload.scope.split(" ").includes("orders:read")
) {
return send(403, { error: "orders:read permission required" });
}
principal = payload.sub;
} catch {
res.setHeader("WWW-Authenticate", 'Bearer error="invalid_token"');
return send(401, { error: "Invalid or expired access token" });
}
const match = /^\/orders\/([a-zA-Z0-9-]{1,64})$/.exec(req.url || "");
if (req.method !== "GET" || !match) return send(404, { error: "Not found" });
try {
const result = await pool.query(
`SELECT o.id, o.status FROM orders o
JOIN principals p ON p.tenant_id = o.tenant_id
WHERE p.subject = $1 AND p.active = true AND o.id = $2`,
[principal, match[1]],
);
// The same 404 covers unknown IDs and orders outside the caller's tenant.
return result.rows[0]
? send(200, result.rows[0])
: send(404, { error: "Order not found" });
} catch {
return send(503, { error: "Order service unavailable" });
}
});
server.requestTimeout = 10_000;
server.listen(
Number(process.env.PORT || 8081),
process.env.HOST || "127.0.0.1",
);Inicializa la base de datos de demo
import { readFile } from "node:fs/promises";
import pg from "pg";
if (!process.env.DATABASE_URL) throw new Error("Set DATABASE_URL");
const deadline = Date.now() + 45_000;
let client;
while (true) {
client = new pg.Client({
connectionString: process.env.DATABASE_URL,
connectionTimeoutMillis: 5000,
statement_timeout: 10000,
});
try {
await client.connect();
break;
} catch {
await client.end().catch(() => {});
if (Date.now() >= deadline)
throw new Error(
"Database unavailable. Check its private endpoint and credentials.",
);
await new Promise((resolve) => setTimeout(resolve, 1000));
}
}
try {
await client.query(
await readFile(new URL("./schema.sql", import.meta.url), "utf8"),
);
console.log("Demo database initialized");
} catch {
throw new Error("Could not initialize the demo database");
} finally {
await client.end();
}La API devuelve el mismo 404 para pedidos inexistentes e inaccesibles, evitando que se descubran IDs de pedidos de otro tenant. Su endpoint público de salud comprueba la conexión a la base de datos sin exponer información ni exigir JWT.
Si ya tienes una API, conserva su modelo de datos y controles de pertenencia. Adapta el endpoint y el mapeo de la respuesta en el manejador MCP. Usa un origen y endpoint fijos en lugar de aceptar URL arbitrarias desde la entrada de la herramienta.
Añade MCP como capa de herramientas sobre la API
Model Context Protocol (MCP) ofrece a los clientes de IA una forma estándar de descubrir y llamar herramientas. Tu servidor describe una herramienta, acepta entradas validadas, realiza la operación y devuelve un resultado. Tu API REST puede seguir atendiendo tu sitio web y otras integraciones.
AI client → HTTPS /mcp → get_order({ order_id: "demo-1001" })
→ GET /orders/demo-1001 → { id: "demo-1001", status: "shipped" }
Client → MCP: MCP_ACCESS_TOKEN, or a user OAuth access token
MCP → API: newly signed API JWT with the verified caller’s subjectEl servidor verifica el JWT del cliente antes de crear un manejador. Cada llamada API usa un JWT nuevo con otra audiencia y el sujeto verificado. La API sigue aplicando las reglas de pertenencia de la base de datos; MCP no las omite.
Usa Streamable HTTP para un servidor remoto. Stdio resulta útil cuando un cliente de escritorio inicia un proceso local. Estos ejemplos HTTP no mantienen estado y devuelven JSON; no requieren almacenamiento de sesiones ni un flujo de eventos persistente. Exponen /mcp para el protocolo y un endpoint público /healthz para la sonda del entorno de ejecución.
Necesitas PostgreSQL y Node.js 24 para la API de ejemplo, y Node.js 24, Python 3.13 o Go 1.25 para el servidor MCP elegido. Instala la Adios CLI y prepara un equipo de Adios. Estos ejemplos usan los SDK oficiales de JavaScript 1.32.1, Python 1.30.0 y Go 1.8.0; evita combinarlos con tutoriales de otras versiones mayores.
Elige una guía por lenguaje
El contrato de la API y el modelo de permisos son los mismos. Continúa con el lenguaje que uses: cada subguía contiene su propio código de servidor, dependencias, comprobaciones del workspace y manifiesto de despliegue de Adios.
JavaScript
Usa el SDK de JavaScript, esquemas de herramientas Zod y Express. Incluye el ejemplo opcional de servidor de recursos OAuth.
Abrir la guía de JavaScriptPython 3.13Python
Usa FastMCP, herramientas tipadas, HTTPX y un control JWT ASGI. Mantén la configuración y el despliegue de Python en una sola guía.
Abrir la guía de PythonGo 1.25Go
Usa el SDK de Go, structs tipados de entrada y salida y middleware HTTP. Compila y despliega un único binario de servicio.
Abrir la guía de GoLas tres implementaciones llaman a la API compartida y verifican los JWT. La guía de JavaScript incluye también el control opcional de acceso OAuth del servidor de recursos; Python y Go explican la autorización necesaria antes de admitir el inicio de sesión de usuarios.
Desarrollar en un workspace de Adios
Usa un equipo de desarrollo de Adios y PostgreSQL administrado. Tu ordenador solo sube el código y ejecuta la comprobación del cliente; los procesos API y MCP se ejecutan en workspaces de Adios.
adios login
adios teams
adios teams switch YOUR_DEV_TEAM_ID
export POSTGRES_PASSWORD="$(openssl rand -hex 32)"
export API_JWT_SECRET="$(openssl rand -hex 32)"
export MCP_JWT_SECRET="$(openssl rand -hex 32)"
printf '%s' "$POSTGRES_PASSWORD" | adios secrets set ORDERS_DB_PASSWORD --stdin
printf '%s' "$API_JWT_SECRET" | adios secrets set ORDERS_API_JWT_SECRET --stdin
printf '%s' "$MCP_JWT_SECRET" | adios secrets set ORDERS_MCP_JWT_SECRET --stdin
adios databases create orders-dev-db --template postgres:16 \
--region de --database orders --user orders_api \
--password-secret ORDERS_DB_PASSWORDEspera a que la base de datos esté lista. Copia su URL de conexión de los detalles de la base de datos en Console y guárdala como ORDERS_DEV_DATABASE_URL mediante entrada secreta. Usa el host asignado y verifica que la región del workspace pueda alcanzarlo.
adios secrets set ORDERS_DEV_DATABASE_URL --stdin
# Paste the database connection URL, then finish stdin with Ctrl-D.
cp api/adios.dev.yaml api/adios.yaml
adios ws create --name orders-api-dev --json
# Copy workspace_id from the response:
export API_WORKSPACE_ID=YOUR_API_WORKSPACE_ID
(cd api && adios sync "$API_WORKSPACE_ID")
adios ws run start "$API_WORKSPACE_ID" --wait --json
adios ws get "$API_WORKSPACE_ID"Primero crea un workspace independiente y luego sincroniza el código. Crear un workspace desde la ruta de un proyecto puede requerir una aplicación ya desplegada; este flujo independiente permite empezar a desarrollar sin publicar una versión.
name: orders-api-dev
region: de
build_cmd: npm ci
start_cmd: npm start
runtime:
name: node@24
port: 8081
health_path: /healthz
env:
API_AUTH_HEADER: X-Orders-Token
HOST: 0.0.0.0
PORT: "8081"
DATABASE_URL: secret://ORDERS_DEV_DATABASE_URL
API_JWT_SECRET: secret://ORDERS_API_JWT_SECRETLa vista previa de la API inicializa el esquema de demostración e inicia el proceso Node.js. Copia su origen HTTPS real del resultado de ejecución o de Console. Mantén este terminal abierto para que el emisor del cliente conserve las claves de firma.
export API_BASE_URL=https://YOUR-API-PREVIEW-HOST
export API_ACCESS_TOKEN="$(node issue-token.mjs orders-api)"
curl --fail "$API_BASE_URL/healthz"
curl --fail -H "Authorization: Bearer $API_ACCESS_TOKEN" \
"$API_BASE_URL/orders/demo-1001"Continúa con la guía de tu lenguaje para crear el workspace MCP. Actualiza los archivos con adios sync y reinicia la vista previa para aplicar los cambios. Una vista previa es un runtime de desarrollo, no una versión publicada de la aplicación.
Elegir una implementación por lenguaje →Detén las vistas previas desde los controles del workspace cuando termines. La base de datos administrada tiene su propio ciclo de vida; detener una vista previa no la detiene ni la elimina.
adios ws run stop "$API_WORKSPACE_ID"Añade OAuth para inicio de sesión y acceso delegado
Los ejemplos JWT cubren una integración controlada con tokens emitidos por el operador. No implementan inicio de sesión, consentimiento ni renovación. Añade OAuth para cuentas personales o cuando el cliente exija el flujo de autorización MCP. El modo OAuth de este ejemplo acepta JWT de acceso emitidos por el proveedor.
Tu servidor MCP es el recurso protegido. Un servidor de autorización gestiona el inicio de sesión, el consentimiento y la emisión de tokens. Tu proveedor OAuth puede hacerlo si admite el descubrimiento y el registro que necesitan tus clientes MCP. Adios aloja la aplicación y guarda secretos; iniciar sesión en la CLI no añade OAuth automáticamente a tu aplicación.
- Publica metadatos del recurso en
/.well-known/oauth-protected-resource/mcp, indicando la URL MCP, el servidor de autorización y los permisos admitidos. - Devuelve 401 para una solicitud sin autenticar con una cabecera
WWW-Authenticateque apunte a esos metadatos. - El cliente descubre los metadatos OAuth u OpenID Connect del servidor de autorización. Configura el registro previo, documentos de metadatos de cliente o registro dinámico según lo que admitan el proveedor y el cliente.
- El usuario inicia sesión y concede acceso. El cliente usa un flujo de código de autorización con PKCE y solicita un token para tu recurso MCP.
- Valida la firma o el resultado de introspección del token, el emisor, la audiencia, la caducidad y los permisos. Asocia el sujeto a tu usuario y tenant antes de ejecutar una herramienta.
Empieza con orders:read. Protege las herramientas de escritura con permisos independientes y confirmación explícita si el cliente la admite. Un token de identidad no es un token de acceso a una API, y un inicio de sesión válido no permite consultar los pedidos de todos los clientes.
La subguía de JavaScript incluye un control opcional completo del servidor de recursos con JWT RS256. Publica los metadatos del recurso y verifica los tokens del proveedor, pero no implementa inicio de sesión, consentimiento, registro de clientes ni emisión de tokens.
Seguir la implementación OAuth de JavaScript →Python y Go necesitan un verificador equivalente de tokens del proveedor y metadatos del recurso antes de aceptar tokens OAuth de usuarios. Un token por sí solo no activa OAuth en las demostraciones JWT.
Una API de terceros puede necesitar otra conexión OAuth. Guarda sus refresh tokens de forma segura, asócialos al usuario correcto y solicita solo los permisos necesarios. Los secretos de cliente del proveedor pertenecen a los secretos de Adios; las URL del emisor y JWKS público son configuración normal.
Referencia del protocolo: Especificación de autorización de MCP.
Despliega PostgreSQL, API y MCP en Adios
Despliega dos aplicaciones: orders-api y orders-mcp. Pueden publicarse de forma independiente. Usa el mismo equipo de Adios para sus referencias a secretos. La región del ejemplo es de; elige una región disponible adecuada para tus usuarios.
Inicia sesión y crea los secretos
Elige el equipo de publicación y genera nuevos secretos de firma y una contraseña de base de datos. Mantén sus datos y credenciales separados del desarrollo. Adios login autentica la CLI en la plataforma.
adios login
adios teams
adios teams switch YOUR_RELEASE_TEAM_ID
export API_JWT_SECRET="$(openssl rand -hex 32)"
export MCP_JWT_SECRET="$(openssl rand -hex 32)"
export POSTGRES_PASSWORD="$(openssl rand -hex 32)"
printf '%s' "$API_JWT_SECRET" | adios secrets set ORDERS_API_JWT_SECRET --stdin
printf '%s' "$MCP_JWT_SECRET" | adios secrets set ORDERS_MCP_JWT_SECRET --stdin
printf '%s' "$POSTGRES_PASSWORD" | adios secrets set ORDERS_DB_PASSWORD --stdinDespliega primero la API
El manifiesto API declara un recurso Postgres gestionado. Adios lo aprovisiona e inyecta DATABASE_URL en el entorno de la API. La contraseña es una referencia a un secreto. El comando de inicio inicializa el esquema de demo antes de arrancar la API; usa tu proceso de migración habitual para producción.
name: orders-api
region: de
replicas: 1
build_cmd: npm ci
start_cmd: npm start
runtime:
name: node@24
port: 8081
health_path: /healthz
resources:
- name: db
template: postgres:16
database: orders
username: orders_api
password: secret://ORDERS_DB_PASSWORD
env:
HOST: 0.0.0.0
PORT: "8081"
API_JWT_SECRET: secret://ORDERS_API_JWT_SECRET
# Adios injects DATABASE_URL for the managed Postgres resource.(cd api && cp adios.release.yaml adios.yaml && adios up)
adios apps get orders-apiadios up compila, despliega y promueve una versión saludable. Es un comando de despliegue, no una vista previa local. Copia la ruta HTTPS real de la salida o de la consola y comprueba que su /healthz devuelve 200.
Conecta MCP con la API desplegada
Edita el manifiesto en el directorio del lenguaje elegido. Sustituye https://api.example.com por el origen real de la API. Sustituye https://mcp.example.com por el origen público del servicio MCP. Son valores de ejemplo, no dominios proporcionados por Adios.
env:
HOST: 0.0.0.0
PORT: "8080"
API_BASE_URL: https://YOUR-API-HOST
PUBLIC_ORIGIN: https://YOUR-MCP-HOST
API_JWT_SECRET: secret://ORDERS_API_JWT_SECRET
MCP_JWT_SECRET: secret://ORDERS_MCP_JWT_SECRETSi aún no conoces el hostname MCP predeterminado, despliega una vez para obtenerlo, actualiza PUBLIC_ORIGIN y vuelve a desplegar antes de conectar un cliente. Las sondas de salud funcionan durante esta configuración; MCP solo acepta su origen configurado. También puedes verificar un dominio personalizado y añadir custom_hosts antes de la publicación final.
custom_hosts:
- mcp.example.comLos manifiestos MCP escuchan en 0.0.0.0, exponen el puerto 8080 y usan /healthz para comprobar la salud. Adios dirige HTTPS al proceso de la aplicación. Mantén la sonda independiente de la autenticación JWT de MCP.
Ejecuta el comando de despliegue desde el directorio de la implementación elegida. Su subguía contiene el comando y el manifiesto exactos.
Abrir los pasos de despliegue de tu lenguaje →Ejecuta la comprobación del cliente contra la URL alojada:
export MCP_ACCESS_TOKEN="$(node issue-token.mjs)"
export MCP_URL=https://YOUR-MCP-HOST/mcp
.client-venv/bin/python check.pyEste tutorial usa una ruta API HTTPS con un JWT de audiencia API. Si mueves la API a una red privada, usa el hostname asignado por Adios y verifica la conectividad desde MCP. No deduzcas un host interno del nombre de la aplicación. Consulta la referencia del manifiesto para las opciones de entorno de ejecución, secretos y rutas.
Usa las herramientas alojadas desde un cliente de IA
En un cliente compatible con Streamable HTTP remoto, añade https://YOUR-MCP-HOST/mcp como URL del servidor. Para los ejemplos privados, configura una cabecera Authorization: Bearer … mediante el mecanismo de secretos o variables de entorno del cliente. No pegues credenciales en archivos de configuración compartidos.
Para OAuth, añade la misma URL y completa el inicio de sesión del cliente. Debe descubrir los metadatos, abrir el inicio de sesión del proveedor y recibir un token de acceso. Comprueba que el cliente admite el flujo de registro del proveedor antes de distribuir la integración.
Comprueba que get_order aparece en la lista de herramientas. Pide: «Usa el servidor Orders MCP para consultar el estado de envío del pedido demo-1001». El cliente puede llamar a la herramienta y responder que se ha enviado. Verifica la llamada real, no solo una respuesta generada a partir del chat.
check.py muestra la inicialización e invocación mediante scripts. Con OAuth puede aceptar un token de acceso válido en MCP_ACCESS_TOKEN, pero no inicia sesión ni renueva tokens; usa un cliente compatible con OAuth para esa experiencia.
Para que un cliente de IA ayude a desplegar este proyecto, conéctalo a Adios MCP. Esa conexión a la plataforma y tu servidor Orders MCP alojado son integraciones independientes con permisos separados.
Comprueba el servicio antes de compartirlo
La ruta de salud de la API comprueba PostgreSQL; la de MCP comprueba su proceso. Ninguna prueba que todos los permisos JWT u OAuth sean correctos. Tras cada publicación, prueba la inicialización, el descubrimiento y una llamada permitida conocida.
- Fallo de conexión: comprueba la ruta, TLS,
/mcpyPUBLIC_ORIGIN. El proxy debe conservar el host previsto y admitir el transporte elegido. - 401 o 403: comprueba las credenciales. Para OAuth, verifica el emisor, la audiencia, la caducidad, los permisos y los metadatos del recurso. Prueba tokens caducados y de audiencia incorrecta junto a uno válido.
- Error de herramienta: comprueba la URL de la API, los permisos de acceso, el tiempo límite y el formato de respuesta. No incluyas tokens ni respuestas privadas en los registros.
- Usuarios reales: añade comprobaciones de tenant y recursos, límites de solicitudes, rotación de credenciales y auditoría asociada al solicitante. Prueba que un usuario no pueda consultar los pedidos de otro.
- Más réplicas: estos ejemplos no guardan estado de sesión. Si añades sesiones, notificaciones o flujos persistentes, planifica el estado compartido y las rutas.
adios logs orders-api --runtime
adios logs orders-mcp --runtime
adios logs orders-mcp --buildFija las versiones de las dependencias y repite la comprobación del cliente tras cambiar rutas o autenticación. Define los permisos y las confirmaciones antes de añadir herramientas de escritura.
Preguntas frecuentes
¿Necesito OAuth para alojar un servidor MCP?
Una integración controlada puede usar un JWT verificado de corta duración si su cliente admite cabeceras de autorización. Para el inicio de sesión, permisos delegados o clientes que requieren el flujo de autorización MCP, implementa OAuth. El inicio de sesión de la CLI Adios no autentica a los usuarios de tu servidor MCP.
¿Puede un servidor MCP conectar con mi API existente?
Sí. Define herramientas con esquemas de entrada, valida cada solicitud, llama a tu API con una credencial destinada a esa API y devuelve resultados estructurados. Comprueba los permisos del solicitante sobre el tenant y los recursos antes de acceder a datos reales.
¿Puedo alojar servidores MCP de JavaScript, Python y Go en Adios?
Sí. Las subguías enlazadas de JavaScript, Python y Go incluyen cada una un servidor Streamable HTTP completo, archivos de dependencias, endpoints de salud y un manifiesto adios.yaml. Elige una y despliégala junto con la API REST compartida.
¿En qué se diferencia de Adios MCP?
Esta guía crea tu propio servicio MCP. Adios MCP permite a un cliente de IA operar espacios de trabajo y despliegues de Adios. Puedes usar esa conexión a la plataforma para crear y desplegar este proyecto.