Skip to content
NimbleBrainNimbleBrainNimbleBrain

Settings sections

A settings section is your connector’s own UI on its settings page, Settings → Connectors → your connector. It is for how your connector behaves in this workspace: changed rarely, and affecting every member. Work people do daily belongs in your app’s main view instead.

It is a capability of the ai.nimblebrain/host block, declared as a placement with slot: "settings", not as a separate top-level object.

Declare it

Section titled “Declare it”
"_meta": {
  "ai.nimblebrain/host": {
    "host_version": "1.0",
    "name": "Support Desk",
    "placements": [
      { "slot": "settings", "resourceUri": "ui://settings" }
    ]
  }
}
Field Meaning for a settings placement
resourceUri The ui:// page that renders the section, served by your server.
priority When you declare more than one settings placement, the host renders the first by priority and ignores the rest.
route, label Ignored. The page already belongs to your connector, so the section claims no navigation: there is no tab, nav entry, or route.

Where it renders

Section titled “Where it renders”

On your connector’s settings page, under a Settings heading, after the host’s connection sections (status, connection, secrets) and before tool permissions.

The host sizes the section to its content, so style it as a section of a page, not as a full viewport. Every workspace member who can open the page sees it, not only admins.

The manage flag

Section titled “The manage flag”

The host tells the section whether the viewer can manage this connector, in the handshake’s host context:

"hostContext": {
  "connector": { "canManage": false }
}
  • canManage is true for a workspace admin, a member of this workspace whose role is admin, and false for everyone else. That includes an organization admin who is not an admin of this workspace. It is the same rule the host’s own sections on the page follow.
  • When it changes while the section is open, the host sends it again in ui/notifications/host-context-changed.
  • Only the settings section receives the connector key. Your other placements do not.

Example

Section titled “Example”

A Support Desk connector keeps a default reply signature per workspace. Any member may read it; only a workspace admin may change it. The catalog entry declares the section and gates the write tool:

"_meta": {
  "ai.nimblebrain/host": {
    "host_version": "1.0",
    "name": "Support Desk",
    "icon": "life-buoy",
    "placements": [
      { "slot": "settings", "resourceUri": "ui://settings" }
    ],
    "admin_tools": ["set_default_signature"]
  }
}

The section reads the flag at the handshake and on every host-context change, and disables the editor when it is false:

// ui://settings. `ctx` is the hostContext from the ui/initialize result,
// or the params of a ui/notifications/host-context-changed notification.
// `callTool` stands for your SDK's tool call (the bridge's `tools/call`).
function applyHostContext(ctx) {
  if (!ctx.connector) return; // a change that did not touch the flag
  const canManage = ctx.connector.canManage === true;
  document.querySelector("#signature").disabled = !canManage;
  document.querySelector("#save").hidden = !canManage;
  document.querySelector("#read-only-note").hidden = canManage;
}


document.querySelector("#save").addEventListener("click", async () => {
  // A non-admin never gets here through the UI. If one calls the tool some
  // other way, the host refuses it with workspace_admin_required.
  await callTool("set_default_signature", {
    signature: document.querySelector("#signature").value,
  });
});

Two layers, each doing one job: canManage keeps a member from being shown a control that would fail, and admin_tools is what makes it fail.

Section titled “Related”