Tutorial - De un Bundle a un Agente Conectado

Este recorrido cubre el camino completo desde una cuenta vacia hasta un agente conectado a un MCP en vivo: crear un bundle, agregarle un MCP, desplegarlo, emitir un token y conectarse. Cada peticion abajo coincide con la firma real de la ruta - copia y pega, sustituyendo tus propios valores.

Todas las peticiones necesitan el encabezado Authorization: Bearer <jwt> descrito en Autenticacion; se omite abajo por brevedad.

1. Encuentra un MCP para agregar

Explora el catalogo para encontrar un listado con el que trabajar:

curl "http://localhost:8000/v1/mcp?q=filesystem"

Anota el id de un listado de la respuesta - ese es el listing_id usado mas abajo.

2. Crea un bundle

Un bundle agrupa uno o mas MCPs bajo un unico endpoint autenticado:

curl -X POST http://localhost:8000/v1/bundles \
  -H "Content-Type: application/json" \
  -d '{"name": "Mi Primer Bundle", "is_public": false}'

{
  "id": "b1f6...",
  "name": "Mi Primer Bundle",
  "is_public": false,
  "entries": []
}

Guarda el id devuelto como bundle_id.

3. Agrega el MCP al bundle

curl -X POST http://localhost:8000/v1/bundles/{bundle_id}/entries \
  -H "Content-Type: application/json" \
  -d '{"listing_id": "<listing_id del paso 1>", "alias": "fs", "auth_strategy": "NONE"}'

alias es como se referencia esta entrada dentro del bundle - no necesita coincidir con el nombre del listado. auth_strategy es "NONE" aqui; los MCPs que necesitan una credencial se configuran en el paso 5 (abajo), despues de que exista el despliegue.

4. Crea un despliegue

Un despliegue es una instancia en ejecucion del bundle, vinculada a ti:

curl -X POST http://localhost:8000/v1/deployments \
  -H "Content-Type: application/json" \
  -d '{"name": "Mi Primer Despliegue", "bundle_id": "<bundle_id>"}'

La respuesta incluye el id del despliegue (deployment_id) y una instantanea de las entradas del bundle al momento de crearlo. Aun no existen credenciales ni tokens.

5. Configura credenciales (si el MCP las necesita)

Omite este paso para los MCPs agregados con auth_strategy: "NONE". De lo contrario:

curl -X PUT http://localhost:8000/v1/deployments/{deployment_id}/credentials/{entry_id} \
  -H "Content-Type: application/json" \
  -d '{"auth_type": "api_key", "credential_json": "{\"key\": \"...\"}"}'

auth_type es uno de bearer, api_key, basic, oauth2_cc, oauth2_pkce, o custom_headers; credential_json es una cadena JSON con el contenido real para ese tipo, cifrada en el servidor antes de almacenarse.

Los MCPs que se autentican via OAuth2 en lugar de una credencial estatica usan un flujo distinto - consulta OAuth2 Initiate para el intercambio PKCE de tres pasos.

6. Emite un token

curl -X POST http://localhost:8000/v1/deployments/{deployment_id}/tokens \
  -H "Content-Type: application/json" \
  -d '{"name": "agent-token"}'

{
  "id": "7a2c...",
  "name": "agent-token",
  "value": "mcpb_live_...",
  "expires_at": null
}

El value se devuelve exactamente una vez - guardalo ahora, no se puede recuperar despues.

7. Conecta

El token del paso 6 es un BundleAccessToken, no un JWT de Keycloak - autentica al daemon de mcpbundler (o a cualquier cliente) para resolver la configuracion en vivo de MCPs del despliegue:

curl http://localhost:8000/v1/bundler/resolve \
  -H "Authorization: Bearer mcpb_live_..."

Esto devuelve la lista completamente resuelta de MCPs, con credenciales descifradas en el servidor para quien la llama - nunca expongas esta respuesta a un cliente de navegador. En la practica, apunta tu instancia de mcpbundler a este token en lugar de llamar directamente a /bundler/resolve; el daemon se encarga del ciclo de resolucion y proxy por ti.