Synapse SDK

What it does

Synapse is a developer SDK for building interactive UI apps that run inside MCP ext-apps hosts (Claude Desktop, VS Code Copilot, ChatGPT, NimbleBrain, and any compatible runtime). It wraps the raw @modelcontextprotocol/ext-apps postMessage handshake and adds a clean, typed API so you can focus on building the UI rather than wiring JSON-RPC plumbing.

One await connect() call gives you immediate access to theme, host info, typed tool calls, reactive data sync, and a Redux-like state store — all with graceful degradation on non-NimbleBrain hosts.

Key features

• Zero-config handshake — await connect() resolves when the host is ready; you never touch ui/initialize directly
• Typed tool calls — call MCP tools with full TypeScript input/output types via app.callTool(name, args)
• Reactive event API — subscribe to tool-result, tool-input, theme-changed, and custom extension events with a unified on() method
• State store — Redux-like typed store with optional persistence and LLM visibility (visibleToAgent: true)
• React hooks — AppProvider, useToolResult, useCallTool, useResize, useStore, and more
• Code generation — CLI (npx synapse) generates TypeScript types from manifests, running servers, or JSON Schema files
• Multi-format bundle — ESM, CJS, IIFE (<script> tag), and a Vite plugin included

Installation

npm install @nimblebrain/synapse @modelcontextprotocol/ext-apps

For React projects:

npm install @nimblebrain/synapse @modelcontextprotocol/ext-apps react

Claude Desktop — register your ext-app bundle in claude_desktop_config.json per your host's ext-apps documentation, then initialise with:

import { connect } from "@nimblebrain/synapse";
const app = await connect({ name: "my-app", version: "1.0.0" });

VS Code Copilot — ext-apps support follows VS Code's MCP extension spec; use the same connect() call inside your iframe entry point.

Claude.ai web — if the host exposes an HTTP ext-apps endpoint, configure the MCP server URL in Claude.ai Settings → Integrations.

Supported hosts

Works in any host implementing the MCP ext-apps protocol. Tested with Claude Desktop, VS Code Copilot, ChatGPT, and NimbleBrain. NimbleBrain-specific features (file picker, platform actions, agent actions) degrade gracefully to no-ops on other hosts.