Skip to content
NimbleBrain NimbleBrain NimbleBrain

App Overview

A NimbleBrain app is an MCPB bundle — a packaged MCP server with a manifest.json. Every app exposes tools that the agent can call. Apps can optionally provide UI rendered inside the NimbleBrain web client as sandboxed iframes, making them full MCP Apps compliant with the ext-apps specification.

How apps integrate

Section titled “How apps integrate”

When you install a bundle, NimbleBrain:

  1. Spawns the MCP server as a subprocess (stdio transport) or connects via HTTP (streamable-http/SSE).
  2. Discovers the server’s tools and registers them in the tool registry.
  3. Reads _meta["ai.nimblebrain/platform"] from manifest.json for UI metadata.
  4. Registers any UI placements in the shell layout (sidebar items, main views).

The agent accesses tools through the tiered tool surfacing system. If the app declares UI metadata, users see the app in the sidebar and can interact with its views directly.

App types

Section titled “App types”

NimbleBrain recognizes two app types:

TypeDetectionDescription
plainDefaultStandard MCP server. Tools only, or tools + optional UI via _meta["ai.nimblebrain/platform"].
upjack_meta["ai.nimblebrain/upjack"] presentAn Upjack declarative app. Automatically gets UI rendering and skill-based behavior.

The type is stored on the BundleInstance and returned in the GET /v1/apps response as the type field.

Architecture

Section titled “Architecture”
┌──────────────────────────────────────────────────────┐
│  manifest.json                                       │
│  ├─ server.mcp_config     → how to spawn the server  │
│  └─ _meta["ai.nimblebrain/platform"]                 │
│       └─ ui.placements[]  → where UI appears         │
└──────────────┬───────────────────────────────────────┘
               │
               ▼
┌──────────────────────────┐     ┌──────────────────────┐
│  MCP Server (subprocess) │     │  Web Client (shell)  │
│  ├─ Tools                │◄───►│  ├─ Sidebar nav      │
│  └─ ui:// Resources      │     │  └─ Iframe views     │
└──────────────────────────┘     └──────────────────────┘
  • Tools are available to the agent via the meta-tool pattern (nb__discover_tools / nb__execute_tool) or surfaced directly when tool count is low.
  • UI resources are HTML pages served by the MCP server via the ui:// protocol and proxied through GET /v1/apps/:name/resources/:path.
  • The MCP App Bridge provides a postMessage channel between iframes and the host for tool calls, navigation, and data sync.

Plain MCP bundle (tools only)

Section titled “Plain MCP bundle (tools only)”

The simplest app is a standard MCP bundle with no UI metadata. It exposes tools to the agent and nothing else:

manifest.json
{
  "name": "@myorg/weather",
  "version": "1.0.0",
  "server": {
    "type": "python",
    "mcp_config": {
      "command": "python",
      "args": ["-m", "weather.server"]
    }
  }
}

MCP bundle with UI

Section titled “MCP bundle with UI”

Add _meta["ai.nimblebrain/platform"] to give your app a presence in the shell:

manifest.json
{
  "name": "@myorg/weather",
  "version": "1.0.0",
  "server": {
    "type": "python",
    "mcp_config": {
      "command": "python",
      "args": ["-m", "weather.server"]
    }
  },
  "_meta": {
    "ai.nimblebrain/platform": {
      "ui": {
        "name": "Weather",
        "icon": "cloud-sun",
        "primaryView": {
          "resourceUri": "ui://dashboard"
        }
      }
    }
  }
}

This registers a main view at /app/@myorg/weather and adds a sidebar entry. The ui://dashboard resource is an HTML page served by your MCP server and rendered in an iframe.

What’s next

Section titled “What’s next”