Synapse — build a UI for an MCP Server

Give an MCP server an interactive UI. The UI is a React app built to one inlined HTML file with @nimblebrain/synapse + Vite, served by the server as the MCP resource ui://<name>/main, and mounted by an MCP Apps host (Claude, ChatGPT, NimbleBrain) in a sandboxed iframe wired to a postMessage bridge. The UI calls the server's existing tools over that bridge — it is data-layer-agnostic and needs no special server framework. Every host speaks the same bridge; they differ in which capabilities they declare, and the SDK behaves predictably when one is missing. Read Portability below before you write components.

Target @nimblebrain/synapse@^0.20.0 (published on npm), with its peers @modelcontextprotocol/ext-apps@^1.7.5 and @modelcontextprotocol/sdk@^1.29.0. A caret range on 0.x does not cross a minor, so an app stays on its pin until someone bumps it deliberately. On NimbleBrain, 0.20.0 needs a host release that declares message, updateModelContext and the ai.nimblebrain/* extensions (nimblebrain#1239): on an earlier host, chat, model context, host actions and key forwarding do nothing and the file picker rejects. The package is the documentation — read its exported types before writing code. Its guides live at synapse.nimblebrain.ai.

Pre-flight — read the SDK's types (the real docs)

From the installed package (node_modules/@nimblebrain/synapse/dist/*.d.ts) or the public repo (github.com/NimbleBrainInc/synapse):

• the react entry — AppProvider and its hooks (useApp, useCallTool, useCallToolAsTask, useDataSync, useTheme, useHostContext, useModelContext, useSendMessage, useAction, useFileUpload, useToolResult, useToolInput, useResize).
• the ui entry — the component library (AppFrame, ListDetailLayout, ListRow, Table, Badge, Prose, ConfirmDialog, tokens, …). Don't hand-roll styling.
• the type exports — ToolCallResult, Theme, the App interface (including hostCapabilities), HostCapabilityError, hostSupports, NIMBLEBRAIN_EXTENSIONS.

Then read references/gotchas.md (non-obvious API facts that each save a debugging cycle) and references/host-contract.md (the NimbleBrain manifest declaration + the bridge). Skim these first; they're short and they're the difference between working and "why is every tool call returning unauthenticated."

Portability — this is an MCP app, not a NimbleBrain app