Skip to content
NimbleBrain NimbleBrain NimbleBrain

App Overview

A NimbleBrain app is an MCP server you deploy and the platform connects to. 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”

An app reaches a workspace as a connector. You run the server; an operator adds it to the connectors catalog as a ServerDetail entry carrying its URL and its _meta["ai.nimblebrain/host"] block; a workspace admin installs it from Browse. The platform then:

  1. Connects to the server’s URL over HTTP (streamable-http or SSE), authenticating per workspace.
  2. Discovers the server’s tools and registers them in the tool registry.
  3. Reads _meta["ai.nimblebrain/host"] from the catalog entry for UI metadata.
  4. Registers any UI placements in the shell layout (sidebar items, main views).
  5. Polls any declared notification outbox into the workspace’s inbox.

The runtime never downloads, verifies, or executes your server’s code — it connects to where you run it. 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.

Architecture

Section titled “Architecture”
┌──────────────────────────────────────────────────────┐
│  Catalog entry (ServerDetail)                        │
│  ├─ remotes[].url         → where the server runs    │
│  └─ _meta["ai.nimblebrain/host"]                     │
│       └─ placements[]     → where UI appears         │
└──────────────┬───────────────────────────────────────┘
               │
               ▼
┌──────────────────────────┐     ┌──────────────────────┐
│  MCP Server (remote)     │     │  Web Client (shell)  │
│  ├─ Tools                │◄───►│  ├─ Sidebar nav      │
│  └─ ui:// Resources      │     │  └─ Iframe views     │
└──────────────────────────┘     └──────────────────────┘
  • Tools are available to the agent via tiered tool surfacing — directly when the tool count is low, otherwise discovered via nb__search (scope: "tools") and invoked through the unified tool namespace.
  • 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.
  • Notifications are the fourth way an app reaches the host, and the only one that does not start with someone asking. An app declares an outbox — one resource holding facts it learned on its own, like a domain going active — and the host pulls from it on a schedule into a workspace inbox the agent can read and an operator can route to Slack, mail, or an agent run.

Tools only

Section titled “Tools only”

The simplest app is a standard MCP server with no UI metadata. Its catalog entry is just a name, a description, and where it runs:

catalog/weather.yaml
servers:
  - name: com.myorg/weather
    description: Current conditions and forecasts
    version: "1.0.0"
    remotes:
      - type: streamable-http
        url: https://weather.myorg.com/mcp

With UI

Section titled “With UI”

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

catalog/weather.yaml
servers:
  - name: com.myorg/weather
    description: Current conditions and forecasts
    version: "1.0.0"
    remotes:
      - type: streamable-http
        url: https://weather.myorg.com/mcp
    _meta:
      ai.nimblebrain/host:
        host_version: "1.0"
        name: Weather
        icon: cloud-sun
        placements:
          - slot: main
            resourceUri: ui://dashboard
            route: weather
            label: Weather
            icon: cloud-sun

This registers a main view at /app/weather and adds a sidebar entry under the “Apps” group. Registration and sidebar placement come from the placements array — 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”