Ein agenten-aware SDK, das das Erstellen von MCP ext-apps durch typisierte Tool-Calls, reaktive Datensynchronisation und React hooks vereinfacht.
Auch bekannt als NimbleBrainInc/synapse, @nimblebrain/synapse
- Stars
- 2
- Tools
- —
- Downloads, 30 Tage
- —
- Neueste Version
- —
- Letzter Commit
- 1. Nov. 2026
- Lizenz
- MIT
Was ist Synapse MCP?
Ein agenten-aware SDK, das das Erstellen von MCP ext-apps durch typisierte Tool-Calls, reaktive Datensynchronisation und React hooks vereinfacht.
Zusammenfassung generiert aus dem README des Projekts
Über Synapse MCP server
Entwickler, die Model Context Protocol Extensions bauen, können Synapse nutzen, um die Erstellung von agenten-aware Anwendungen zu vereinfachen. Dieses SDK fungiert als Enhancement-Layer für das ext-apps Protokoll und bietet eine einheitliche Möglichkeit, User Interfaces zu bauen, die innerhalb von Hosts wie Claude Desktop, VS Code, ChatGPT oder NimbleBrain laufen. Es übernimmt die komplexe Infrastruktur des Protokolls, wie den initialen Handshake und das Tracking von JSON-RPC Requests, über einen einzigen connect command.
Das SDK bietet verschiedene spezialisierte Tools für unterschiedliche Development-Workflows, darunter React hooks für die reaktive Datensynchronisation, eine Component Library für konsistente Layouts und ein CLI zur Generierung von TypeScript-Typen aus Manifesten oder JSON-Schemas. Es verwaltet kritische UI-Aspekte wie Theme-Tracking für Light- und Dark-Modes, das Weiterleiten von Tastenkombinationen und das automatische Resizing basierend auf der verfügbaren Pane-Breite. Für alle, die mit Python arbeiten, steht ein dediziertes Package zur Verfügung, um kompatible Komponenten zu bauen.
Was du damit machen kannst
- 1UI mit Agent-Daten synchronisierenEin Entwickler kann sicherstellen, dass seine Anwendungsoberfläche aktuell bleibt, indem er auf Server-Notifications reagiert, wenn sich Resources ändern.
- 2Kontext an die KI liefernDu kannst spezifische User-Interaktionen oder View-States direkt an das Modell pushen, um die Agent Awareness zu verbessern.
- 3Type Safety automatisierenEntwickler können vollständige TypeScript-Definitionen für ihre Tools generieren, indem sie bestehende Manifeste oder laufende Server nutzen.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
So installierst du Synapse MCP
Formate geprüft am 10. Nov. 2026Zu Cursor hinzufügenZu Goose hinzufügenSynapse MCP in Claude Code installieren
$ claude mcp add synapse -- npx -y @nimblebrain/synapseSynapse MCP in Cursor installieren
~/.cursor/mcp.json
{
"mcpServers": {
"synapse": {
"command": "npx",
"args": [
"-y",
"@nimblebrain/synapse"
]
}
}
}Synapse MCP in VS Code installieren
.vscode/mcp.json
{
"servers": {
"synapse": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@nimblebrain/synapse"
]
}
}
}Synapse MCP in VS Code CLI installieren
$ code --add-mcp '{"name":"synapse","type":"stdio","command":"npx","args":["-y","@nimblebrain/synapse"]}'Synapse MCP in Claude Desktop installieren
claude_desktop_config.json
{
"mcpServers": {
"synapse": {
"command": "npx",
"args": [
"-y",
"@nimblebrain/synapse"
]
}
}
}Synapse MCP in Codex installieren
$ codex mcp add synapse -- npx -y @nimblebrain/synapseSynapse MCP in Codex config.toml installieren
~/.codex/config.toml
[mcp_servers.synapse] command = "npx" args = ["-y", "@nimblebrain/synapse"]
Synapse MCP in Gemini CLI installieren
$ gemini mcp add -s user synapse npx -- -y @nimblebrain/synapseSynapse MCP in Gemini settings.json installieren
~/.gemini/settings.json
{
"mcpServers": {
"synapse": {
"command": "npx",
"args": [
"-y",
"@nimblebrain/synapse"
]
}
}
}Automatisierte Checks
Geluften am 14. Nov. 2026Vollständiger Bericht →Unsere automatisierten Checks bestanden. Das ist kein Security-Audit: Lies den Code und gib dem Server nur den minimal notwendigen Zugriff. Wie die Checks funktionieren
- Source Repository verknüpft und erreichbarnimblebraininc/synapse is public and reachablegithub.com/nimblebraininc/synapse ↗Bestanden
- Paket nennt dieses Repository als Quelle@nimblebrain/synapse names nimblebraininc/synapse as sourcenpmjs.com/package/@nimblebrain/synapse ↗Bestanden
- Build-Provenienz (Sigstore-Attestierung)Sigstore attestation for @nimblebrain/synapsenpmjs.com/package/@nimblebrain/synapse/v/0.39.0#provenance ↗Bestanden
- Open Source Lizenz (OSI)MITspdx.org/licenses/MIT.html ↗Bestanden
- Commit oder Release im letzten JahrLast commit or release 2026-11-01github.com/nimblebraininc/synapse ↗Bestanden
- OpenSSF ScorecardNicht geprüft
- Package-Name ähnelt keinem populären PackageNo popular package one edit away from @nimblebrain/synapseBestanden
- Keine kritischen Advisories im Paket oder seinen AbhängigkeitenNicht geprüft
- Keine versteckten Anweisungen an das Modell0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersBestanden
- Destruktive Tools sind markiertNicht geprüft
- Remote-Endpoint beantwortet den MCP-HandshakeNicht geprüft
README
Auf GitHub ansehen@nimblebrain/synapse
Agent-aware app SDK for the MCP ext-apps protocol. One await connect() and you're live — typed tool calls, reactive data sync, and React hooks that work in any host implementing ext-apps (Claude Desktop, VS Code, ChatGPT, NimbleBrain, or your own runtime).
What is Synapse?
Synapse is an optional enhancement layer over @modelcontextprotocol/ext-apps. It wraps the ext-apps protocol handshake and adds:
- Zero-config handshake —
await connect()resolves when the host is ready. You never seeui/initialize. - Typed tool calls — call MCP tools with full TypeScript input/output types
- Reactive data sync — refresh when your server announces its data changed (
notifications/resources/list_changed) - Theme tracking — automatic light/dark mode and custom design tokens
- Agent context — push what the user is looking at to the model with
useModelContext - Keyboard forwarding — forward shortcuts from sandboxed iframes to the host
- Code generation — generate TypeScript types from manifests, running servers, or JSON schemas
Every call checks what the host declared in ui/initialize. Where a capability is missing, the call does a documented thing: it sends nothing, it keeps its initial value, or it rejects with HostCapabilityError without sending. See the portable-app contract.
Why Synapse?
Raw ext-apps gives you an iframe and postMessage. That works — until the agent changes data and your UI goes stale, or the user filters a view and the agent can't see what they're looking at, or you spend an afternoon wiring up JSON-RPC request tracking for the third time.
Synapse handles the plumbing so you can focus on the UI. See Why Synapse? for before/after comparisons of each problem it solves.
Install
npm install @nimblebrain/synapse
Peer dependencies: @modelcontextprotocol/ext-apps@^2.0.0, @modelcontextprotocol/client@^2.0.0, @modelcontextprotocol/core@^2.0.0 (and zod@^4.2.0, which ext-apps requires)
Building a Python MCP server? The server half — one self-contained ui://
component rendered across ChatGPT, Claude, and NimbleBrain — ships as the
nimblebrain-synapse PyPI package (pip install nimblebrain-synapse).
Package Exports
| Entry Point | Description |
|---|---|
@nimblebrain/synapse |
Vanilla JS core — connect(), plus the helpers over an App: callToolAsTask(), open(), openConnectorSettings(), pickFile(), pickFiles(), uploadFiles(), notify(), downloadFile() |
@nimblebrain/synapse/host |
Cross-host UI client, with no React or @modelcontextprotocol/* dependency: connectUI() for ChatGPT, Claude, NimbleBrain, and standalone, plus the gutter defaults (GUTTER_DEFAULT, GUTTER_NARROW_DEFAULT, GUTTER_NARROW_BREAKPOINT) |
@nimblebrain/synapse/react |
React hooks and the AppProvider |
@nimblebrain/synapse/ui |
Component library — tokens, primitives, components, layouts |
@nimblebrain/synapse/ui/base |
Side-effect import that establishes the root-height chain (html, body, #root) the app shell fills. AppFrame does this automatically on render; import it in your entry to apply it before first paint |
@nimblebrain/synapse/vite |
Vite plugin for dev mode |
@nimblebrain/synapse/codegen |
CLI + programmatic code generation |
@nimblebrain/synapse/iife |
Pre-built IIFE bundle for <script> tags (window.Synapse) |
UI Components (@nimblebrain/synapse/ui)
A React component library for embedded Synapse apps: a token contract, layout
primitives (Stack, Inline, …), components (Card, Badge, Drawer, ConfirmDialog,
Table, ListRow, …), and responsive layout scaffolds (AppFrame,
SidebarLayout, ListDetailLayout). The gallery/ app is a living reference —
every token and component in light/dark across several themes.
Design principles
These are the durable decisions behind the library; they rarely change.
- The library holds no brand. Tokens are
var(--token, neutral-fallback)references, not hex values. The host injects the real palette at runtime (the MCP ext-appshostContext.styles.variables), so the same app adopts whatever host it runs in. Standalone, it renders in neutral fallbacks. - That includes typography — the SDK ships no fonts. Font fallbacks are
web-safe system stacks, so an app renders correctly with no host, no network,
and no font files. A host that wants its own typeface sends
@font-faceCSS in the host context (styles.css.fonts); the library fetches nothing on its own. See Host fonts. - Theme via CSS, not React. Components style with token-driven inline-style
objects whose values are those
var()refs, so theming — including light/dark — resolves in CSS with no re-render.ensureStyleinjects keyframes and pseudo-state rules once; brand values never get baked in. - Scaffold only genuinely-complex layouts.
AppFrame,SidebarLayout, andListDetailLayoutexist because they encapsulate real responsive/stateful complexity. Boards, grids, and simple lists are primitives + recipes, not components — the library codifies the shapes apps actually take, not a general layout engine. - Responsive to the pane, not the device. Layouts observe their own width
(
ResizeObserverviauseBreakpoint), because an app's iframe may be fullscreen, split, or a narrow rail regardless of screen size. - Sandbox-safe overlays.
DrawerandConfirmDialogare plain<div>overlays, not a native<dialog>: the app iframe withholdsallow-modals, so<dialog>.showModal()throws there. The scrim, Tab focus trap, focus-in/restore, scroll-lock, and Escape are hand-rolled once and shared, and the innermost open overlay owns Escape and Tab, so a confirmation raised inside a drawer closes without closing the drawer.
Host fonts
A CSS custom property can name a font family but cannot load one, and an app
iframe is its own document — it inherits no @font-face from the host page. So a
host that sends only tokens is naming a typeface the app has no way to render.
The MCP Apps spec closes that gap with styles.css.fonts: the host sends
@font-face CSS in the host context, and the SDK loads it into the app document.
// Host side — the hostContext of ui/initialize.
{
theme: "dark",
styles: {
variables: { "--font-sans": "'Your Sans', system-ui, sans-serif" },
css: {
fonts: "@font-face { font-family: 'Your Sans'; src: url('/fonts/your-sans.woff2') format('woff2'); font-weight: 400 700; font-display: swap; }",
},
},
}
Three things worth knowing:
- Sending no fonts is a supported configuration, not a degraded one. Omit
styles.css.fontsand the app renders in the web-safe fallbacks (system-uifor both body and headings,ui-monospacefor code). - Give every
--font-*token value a web-safe tail. A bare family name with no matching face falls through to the browser default, not to your intended stack."'Your Sans', system-ui, sans-serif", never"'Your Sans'". - The URL must satisfy the app iframe's CSP — and
'self'may not mean what you expect. A host that mounts apps in asrcdociframe withoutallow-same-origin(the usual choice, since granting it to third-party app HTML is a sandbox escape) gives the frame an opaque origin, and CSP'self'then matches nothing. Under a typicalfont-src 'self' data:, adata:URI is the only form that works unconditionally; any http(s) URL — self-hosted or CDN — needs the host to add that origin to the frame's CSP. Check the host's policy before choosing between them.
Faces load alongside the token variables, on the handshake and on every
host-context-changed that carries styles.css.fonts. A context change without
them keeps the faces already loaded, so a theme toggle never unloads the host's
typeface.
Quick Start
Vanilla JS
import { connect } from "@nimblebrain/synapse";
const app = await connect({ name: "my-app", version: "1.0.0" });
// Theme, host info, and tool context are available immediately
console.log(app.theme.mode); // "dark"
console.log(app.hostInfo); // { name: "nimblebrain", version: "2.0.0" }
// Subscribe to tool results from the agent
app.on("tool-result", (data) => {
console.log(data.content); // parsed JSON or raw string
});
// Call an MCP tool
const result = await app.callTool("get_items", { limit: 10 });
console.log(result.data);
// Tell the agent what the user sees
app.updateModelContext(
{ selectedItem: "item-42" },
"User is viewing item 42",
);
React
import { AppProvider, useToolResult, useResize } from "@nimblebrain/synapse/react";
function App() {
return (
<AppProvider name="my-app" version="1.0.0">
<ItemList />
</AppProvider>
);
}
function ItemList() {
const result = useToolResult();
const resize = useResize();
useEffect(() => { if (result) resize(); }, [result, resize]);
if (!result) return <p>Waiting for data...</p>;
return result.content.items.map((item) => <div key={item.id}>{item.name}</div>);
}
Script Tag (IIFE)
Drop a single <script> tag — no bundler required:
<script src="https://unpkg.com/@nimblebrain/synapse/dist/connect.iife.global.js"></script>
<script>
Synapse.connect({ name: "widget", version: "1.0.0", autoResize: true })
.then(app => {
app.on("tool-result", (data) => {
document.getElementById("root").innerHTML = render(data.content);
});
});
</script>
Vite Plugin
// vite.config.ts
import { synapseVite } from "@nimblebrain/synapse/vite";
export default {
plugins: [
synapseVite({
appName: "my-app",
}),
],
};
Code Generation
Generate TypeScript types from an app manifest:
npx synapse --from-manifest ./manifest.json --out src/generated/types.ts
Or from a running MCP server:
npx synapse --from-server http://localhost:3000 --out src/generated/types.ts
Or from a directory of .schema.json files (generates CRUD tool types):
npx synapse --from-schema ./schemas --out src/generated/types.ts
Handling Events
The App object returned by connect() uses a unified on() method for all events. Each call returns an unsubscribe function.
const app = await connect({ name: "my-app", version: "1.0.0" });
// Tool results from the agent (parsed content, not raw JSON-RPC)
const unsub = app.on("tool-result", (data) => {
console.log(data.content); // parsed JSON or raw string
console.log(data.structuredContent); // structuredContent if host sent it
console.log(data.raw); // original params for advanced use
});
// Tool input arguments (what the agent is calling with)
app.on("tool-input", (args) => {
console.log(args); // Record<string, unknown>
});
// Theme changes
app.on("theme-changed", (theme) => {
document.body.classList.toggle("dark", theme.mode === "dark");
});
// Lifecycle — clean up when the host tears down the view
app.on("teardown", () => {
saveState();
});
// Any wire method works as a passthrough event name — here, your server
// announcing that its data changed (which is what useDataSync listens for)
app.on("notifications/resources/list_changed", (params) => {
refreshData();
});
// Unsubscribe when done
unsub();
on() Event |
Spec Method | Data |
|---|---|---|
"tool-result" |
ui/notifications/tool-result |
ToolResultData (parsed) |
"tool-input" |
ui/notifications/tool-input |
Record<string, unknown> |
"tool-input-partial" |
ui/notifications/tool-input-partial |
Record<string, unknown> |
"tool-cancelled" |
ui/notifications/tool-cancelled |
— |
"theme-changed" |
ui/notifications/host-context-changed |
Theme — fires only when the theme actually moves |
"host-context-changed" |
ui/notifications/host-context-changed |
McpUiHostContext — every change, unfiltered |
"teardown" |
ui/resource-teardown |
— |
| Any custom string | Passed through as-is | unknown |
API Reference
connect(options)
The one entry point. Creates a connected App instance. The returned promise resolves after the ext-apps handshake completes — theme, host info, and tool context are available immediately.
import { connect } from "@nimblebrain/synapse";
const app = await connect({ name: "my-app", version: "1.0.0" });
| Option | Type | Description |
|---|---|---|
name |
string |
App name (must match registered bundle name) |
version |
string |
Semver version |
autoResize |
boolean? |
Observe document.body and auto-send size-changed. Default: false |
forwardKeys |
boolean | KeyForwardConfig[]? |
Forward keyboard shortcuts to the host. Only a NimbleBrain host consumes them, so it stays off elsewhere. |
on |
Record<string, (data) => void>? |
Pre-register handlers before the handshake, so no early message is lost |
App Properties
| Property | Type | Description |
|---|---|---|
theme |
Theme |
Current theme (mode, tokens) |
hostInfo |
{ name, version } |
Host identity |
toolInfo |
{ tool } | null |
Tool context if launched from a tool call |
containerDimensions |
Dimensions | null |
Container size constraints from host |
hostContext |
McpUiHostContext |
The full host context — spec fields plus host extensions |
destroyed |
boolean |
True after destroy() |
supportsTasks |
boolean |
Whether the host declared the MCP tasks extension (io.modelcontextprotocol/tasks) |
App Methods
| Method | Description |
|---|---|
on(event, handler) |
Subscribe to events. Returns unsubscribe function. |
resize(width?, height?) |
Send size to host. Auto-measures document.body if no args. |
openLink(url) |
Open a URL (host-aware) |
updateModelContext(state, summary?) |
Push LLM-visible state |
callTool(name, args?) |
Call a tool on this app's own MCP server and get a typed result |
readServerResource({ uri }) |
Read an MCP resource from the originating server |
sendMessage(text) |
Send a message into the agent conversation |
destroy() |
Clean up all listeners, observers, and timers |
Helpers over an App
The App object carries the ext-apps surface and the state the handshake
established. Everything else is a function that takes an app — imported from the
package root — so the object stays small and an app that never picks a file
never carries the picker.
import { connect, open, pickFile, downloadFile, callToolAsTask } from "@nimblebrain/synapse";
const app = await connect({ name: "my-app", version: "1.0.0" });
await open(app, "files://fl_abc123");
| Function | Description |
|---|---|
callToolAsTask(app, name, args?) |
Call a tool the server may run as a task; returns a Promise<TaskHandle>. See Long-running tools. |
open(app, uri) |
Ask the host to open what a resource URI names: a record, a conversation (conversation://…), an app's own screen (its ui:// resource) or a view another app reports in its trail. The host finds what shows it. Resolves true once the host put it on screen and handed it the URI (whether an app then shows that view is the app's), and false without sending unless the host declares ai.nimblebrain/open. Rejects with the host's error when nothing in the workspace shows the URI. |
openConnectorSettings(app) |
Ask the host to open this connector's settings page; the host knows which connector sent it. Resolves true once opened, and false without sending unless the host declares ai.nimblebrain/open-connector-settings. Rejects with the host's error when the connector has none. |
pickFile(app, options?) |
Native file picker, single file. Rejects with HostCapabilityError unless the host declares ai.nimblebrain/request-file. |
pickFiles(app, options?) |
Native file picker, multiple files. Rejects with HostCapabilityError unless the host declares ai.nimblebrain/request-file. |
uploadFiles(app, files, options?) |
Store Files the app already holds (dropped on it, say), answered like a pick. Rejects with HostCapabilityError unless the host declares ai.nimblebrain/upload-files. |
notify(app, { level, title, description? }) |
Ask the host to show the user a notice, labelled with your app. level is success, info, warning or error; title is 1–120 characters, description up to 500. Resolves true once shown, and false without sending unless the host declares ai.nimblebrain/notify. Rejects with the host's error when it refuses one. |
hostSupports(app, extension) |
Whether the host declared a NimbleBrain extension ("open", "openConnectorSettings", "notify", "requestFile", "uploadFiles", "keydown", "location"). |
downloadFile(app, name, content, mime?) |
Hand the user a file to save, over the spec's ui/download-file. Resolves with the host's result — { isError: true } when the host declined or the user cancelled — and rejects, without sending, when the host did not advertise the downloadFile capability. |
app.supportsTasks says whether the host declared the MCP tasks extension.
callToolAsTask throws when it is false, so read it to decide
whether to offer a long-running action at all rather than to discover the answer
from an exception.
A host declares it in
hostCapabilities.experimental["io.modelcontextprotocol/tasks"], the MCP tasks
extension identifier, and nowhere else; presence is the signal, so {} is a
declaration. A top-level hostCapabilities.tasks is
not read, because a spec client's handshake parse strips it.
React Hooks
Wrap your tree in <AppProvider> — it takes the same options as connect() and
renders nothing until the handshake completes, so nothing below it can observe a
half-connected app.
import { AppProvider, useApp, useCallTool, useTheme } from "@nimblebrain/synapse/react";
| Hook | Returns | Description |
|---|---|---|
useApp() |
App |
The connected app |
useTheme() |
Theme |
Reactive theme. Re-renders only when the theme actually moves. |
useHostContext<T>() |
T |
The full host context, including host extensions |
useToolResult() |
ToolResultData | null |
Re-renders on every tool-result event |
useToolInput() |
Record<string, unknown> | null |
Re-renders on every tool-input event |
useResize() |
(w?, h?) => void |
Resize helper — auto-measures body if no args |
useCallTool(name) |
{ call, data, isPending, error } |
Call a tool with loading/error state |
useCallToolAsTask(name) |
{ fire, task, result, error, isWorking, isTerminal, cancel } |
The full task lifecycle for a long-running tool. See below. |
useDataSync(cb) |
— | Run cb when your server announces its data changed (notifications/resources/list_changed); cb gets the latest notification's params. A burst runs cb once, and while a promise cb returned is pending, later notices run it once after it settles. Also runs cb (with {}, same single-flight) when the view is shown after a minute or more hidden |
useModelContext() |
(state, summary?) => void |
Push LLM-visible state, debounced 250ms |
useModelContext(factory, deps) |
— | The same, pushed whenever deps change |
useSendMessage() |
(text) => void |
Send a message into the agent conversation |
useOpen() |
(uri) => Promise<boolean> |
Open what a resource URI names, through the host. See open |
useOpenConnectorSettings() |
() => Promise<boolean> |
Open this connector's settings page through the host. See openConnectorSettings |
useNotify() |
(notice) => Promise<boolean> |
Show the user a notice through the host, labelled with your app. See notify |
useFileUpload() |
{ pickFile, pickFiles, uploadFiles, isPending } |
The host's native file picker, and uploads of files the app holds (NB-only) |
Synapse MCP Fragen
Wie füge ich Synapse MCP zu Claude Code hinzu?
Führe claude mcp add synapse -- npx -y @nimblebrain/synapse in deinem Terminal aus. Füge --scope user hinzu, damit der Server in jedem Projekt verfügbar ist.
Wie füge ich Synapse MCP zu Cursor hinzu?
Öffne ~/.cursor/mcp.json und füge den Server unter mcpServers hinzu, mit der Cursor-Config aus dem Installationsabschnitt oben.
Was unterscheidet Synapse von herkömmlichen ext-apps?
Synapse bietet eine Enhancement-Layer, die Zero-Config Handshakes, typisierte Tool-Calls, reaktive Datensynchronisation, Theme-Tracking und Agent Context übernimmt.
Kann ich Synapse mit einem Python MCP server nutzen?
Ja, du kannst das nimblebrain-synapse PyPI Package nutzen, um eine eigenständige UI-Komponente für Python-Server bereitzustellen.
Wie handhabt Synapse Themes und Fonts?
Das SDK nutzt CSS-Variablen für das Theming, sodass es die Farbpalette des Hosts ohne Re-renders übernimmt. Zudem kann es vom Host bereitgestelltes @font-face CSS in das App-Dokument laden.
Unterstützt Synapse Code-Generierung?
Ja, es enthält ein CLI und programmatische Tools, um TypeScript-Typen aus Manifesten, laufenden Servern oder JSON-Schemas zu generieren.