Tutorial - Bundle to Connected Agent

This walks through the complete path from an empty account to an agent connected to a live MCP: create a bundle, add an MCP to it, deploy it, issue a token, and connect. Every request below matches the actual route signatures - copy/paste and substitute your own values.

All requests need the Authorization: Bearer <jwt> header described in Authentication; it's omitted below for brevity.

1. Find an MCP to add

Browse the catalog for a listing to work with:

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

Note the id of a listing from the response - that's the listing_id used below.

2. Create a bundle

A bundle groups one or more MCPs under one authenticated endpoint:

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

{
  "id": "b1f6...",
  "name": "My First Bundle",
  "is_public": false,
  "entries": []
}

Save the returned id as bundle_id.

3. Add the MCP to the bundle

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

alias is how this entry is addressed within the bundle - it doesn't need to match the listing's own name. auth_strategy is "NONE" here; MCPs that need a credential are configured in step 5 (below) after the deployment exists.

4. Create a deployment

A deployment is a running instance of the bundle, bound to you:

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

The response includes the deployment's id (deployment_id) and a snapshot of the bundle's entries at creation time. No credentials or tokens exist yet.

5. Configure credentials (if the MCP needs one)

Skip this step for MCPs added with auth_strategy: "NONE". Otherwise:

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 is one of bearer, api_key, basic, oauth2_cc, oauth2_pkce, or custom_headers; credential_json is a JSON-serialized string holding the actual payload for that type, encrypted server-side before storage.

MCPs that authenticate via OAuth2 instead of a static credential use a different flow - see OAuth2 Initiate for the three-step PKCE exchange.

6. Issue a 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
}

The value is returned exactly once - store it now, it cannot be retrieved again later.

7. Connect

The token from step 6 is a BundleAccessToken, not a Keycloak JWT - it authenticates the mcpbundler daemon (or any client) to resolve the deployment's live MCP configuration:

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

This returns the fully resolved list of upstream MCPs, with credentials decrypted server-side for the caller - never surface this response to a browser client. In practice, point your mcpbundler instance at this token rather than calling /bundler/resolve directly; the daemon handles the resolve-and-proxy loop for you.