Bundle Configuration

The bundles array in nimblebrain.json declares which MCP server bundles to spawn at startup. Each entry can reference a bundle from the mpak registry by name, a local directory by path, or a remote MCP server by URL.

Bundles declared in the config file are merged with the default bundles (@nimblebraininc/bash) unless you set noDefaultBundles: true.

Bundle types

Every bundle entry must include exactly one of name, path, or url.

Named bundles (registry)

Install a bundle from the mpak registry by its scoped name.

{
  "bundles": [
    { "name": "@nimblebraininc/tasks" },
    { "name": "@nimblebraininc/postgres" }
  ]
}

NimbleBrain downloads the bundle from mpak, reads its manifest, spawns the MCP server process, and registers its tools.

Local bundles (path)

Point to a bundle directory on the local filesystem. Paths are resolved relative to the config file location.

{
  "bundles": [
    { "path": "../mcp-servers/hello" },
    { "path": "/opt/bundles/my-custom-server" }
  ]
}

The directory must contain a valid MCPB manifest.json with an mcp_config section that tells NimbleBrain how to spawn the server process.

Remote bundles (url)

Connect to an MCP server running at a remote URL. You must provide a serverName for display and tool namespacing.

{
  "bundles": [
    {
      "url": "https://mcp.example.com/mcp",
      "serverName": "example",
      "transport": {
        "type": "streamable-http",
        "auth": { "type": "bearer", "token": "sk-..." }
      }
    }
  ]
}

Remote bundles do not download or spawn a local process. Instead, NimbleBrain connects to the server over HTTP using the specified transport configuration.

Common fields

These fields apply to all bundle types.

Field	Type	Default	Description
env	object	{}	Environment variables passed to the bundle process. Each key-value pair is a string.
protected	boolean	false	When true, the bundle cannot be uninstalled via the nb__manage_bundle tool or the API.
trustScore	number | null	null	MTF trust score (0—100) recorded at install time. Set automatically by the install flow.
ui	object | null	null	UI metadata from the bundle manifest. Set automatically at install time.

Passing environment variables

Use env to inject secrets or configuration into a bundle process:

{
  "bundles": [
    {
      "name": "@nimblebraininc/postgres",
      "env": {
        "DATABASE_URL": "postgres://localhost:5432/mydb",
        "PG_MAX_CONNECTIONS": "10"
      },
      "protected": true
    }
  ]
}

Tip

For sensitive values, consider using the nb config set command instead of putting secrets directly in the config file. Values set via nb config set are mapped to environment variables through the bundle manifest’s user_config declarations.

UI metadata

The ui field is populated automatically when you install a bundle that declares UI metadata in its manifest. You do not need to set this manually.

{
  "ui": {
    "name": "Tasks",
    "icon": "clipboard",
    "primaryView": {
      "resourceUri": "ui://tasks/index.html"
    }
  }
}

Field	Type	Description
ui.name	string	Human-readable app name shown in the sidebar.
ui.icon	string	Emoji or icon identifier.
ui.primaryView.resourceUri	string	ui:// resource URI for the app’s full-page view.

Remote transport configuration

Remote bundles accept a transport object that controls how NimbleBrain connects to the server.

{
  "url": "https://mcp.example.com/mcp",
  "serverName": "example",
  "transport": {
    "type": "streamable-http",
    "auth": { "type": "bearer", "token": "sk-..." },
    "headers": {
      "X-Custom-Header": "value"
    },
    "reconnection": {
      "maxRetries": 5,
      "initialReconnectionDelay": 1000,
      "maxReconnectionDelay": 30000
    },
    "sessionId": "resume-session-abc123"
  }
}

Transport fields

Field	Type	Default	Description
type	"streamable-http" | "sse"	"streamable-http"	Transport protocol. Streamable HTTP is the default MCP transport. Use "sse" for servers that only support Server-Sent Events.
auth	object	—	Authentication method. See auth types.
headers	object	{}	Custom HTTP headers sent with every request. Keys and values are strings.
reconnection	object	—	Reconnection behavior. See reconnection.
sessionId	string	—	MCP session ID for resuming an existing session.

Auth types

Bearer token

{
  "auth": {
    "type": "bearer",
    "token": "sk-your-api-key"
  }
}

Sends an Authorization: Bearer <token> header with every request.

Custom header

{
  "auth": {
    "type": "header",
    "name": "X-API-Key",
    "value": "your-api-key"
  }
}

Sends a custom header with every request. Use this for APIs that expect a non-standard auth header.

No auth

{
  "auth": {
    "type": "none"
  }
}

No authentication headers are sent. Use this for servers on a private network or behind a VPN.

Reconnection

Control how NimbleBrain handles dropped connections to remote servers.

Field	Type	Description
maxRetries	number	Maximum number of reconnection attempts before giving up.
initialReconnectionDelay	number	Milliseconds to wait before the first retry.
maxReconnectionDelay	number	Maximum milliseconds between retries (backs off exponentially up to this cap).

Disabling default bundles

By default, NimbleBrain spawns @nimblebraininc/bash alongside your configured bundles. To disable this:

{
  "noDefaultBundles": true,
  "bundles": [
    { "name": "@nimblebraininc/tasks" }
  ]
}

Caution

Disabling default bundles removes the shell tool that many skills rely on. Only use this if you have specific security or isolation requirements.

Complete example

A config file with all three bundle types:

{
  "$schema": "https://schemas.nimblebrain.ai/nimblebrain.json",
  "version": "1",
  "bundles": [
    {
      "name": "@nimblebraininc/postgres",
      "env": { "DATABASE_URL": "postgres://localhost:5432/mydb" },
      "protected": true
    },
    {
      "path": "./my-local-server"
    },
    {
      "url": "https://mcp.example.com/mcp",
      "serverName": "example-remote",
      "transport": {
        "type": "streamable-http",
        "auth": { "type": "bearer", "token": "sk-..." },
        "headers": { "X-Tenant": "acme" },
        "reconnection": {
          "maxRetries": 3,
          "initialReconnectionDelay": 1000,
          "maxReconnectionDelay": 10000
        }
      }
    }
  ]
}