Fusebase MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
FuseBase MCP Server
An unofficial Model Context Protocol (MCP) server enabling autonomous AI coding agents and developers to programmatically manage FuseBase (formerly Nimbus Note) workspaces - collaborative Y.js documents, relational tables, ActivePieces automations, client portals, hosted web apps, and multi-agent swarm boards. Live test suites prove every write by reading the data back from FuseBase (docs/TESTING.md).
Project Status Dashboard
Production Status & Interactive Architecture Dashboard: fusebase-mcp.thefusebase.app
Engineering status, a searchable directory of released MCP tools with schema parameters, test suite metrics, system architecture, and milestone chronology. Local unreleased changes are documented in CHANGELOG.md.
Validation status
The November 4, 2026 remediation run passed all 17 selected stages, including 1,783 live assertions and verified fixture cleanup. After a further cleanup regression fix, 540 unit tests pass on Windows Node 22.19 and Node 26; the portal lifecycle and sweep were retested successfully. Clean Linux Node 22.19 installation, offline checks and packed-package checks also pass.
These figures describe the November 4 working-tree validation. Dashboard evidence states and nine browser checks are now implemented. Each release requires fresh source-matched checks, passing remote CI and exact deployment verification. See the remediation progress for source identities and scope.
Earlier focused live checks verified automation outputs, account restoration, hosted deployment/logs, portal invitation and email delivery, login links, agent execution and actual web extraction. Temporary remote fixtures were removed and cleanup was read back. The separate Paperclip API still requires permissions absent from the tested token; one intermittent malformed agent stream remains a documented reliability observation. See the live validation report for evidence and limits.
Related MCP server: Fizzy MCP Server
Capabilities
177 tools across content, tasks, members, files, databases, org admin, portals, guides, vibe coding, automations, CLI lifecycle, AI assistants & agent threads, FuseBase Work (Firecrawl & n8n), direct Gate & Dashboards MCP tokens, billing, user preferences, multi-agent profiles, and swarm orchestration
Direct Gate & Dashboards MCP Token Mode: Connect zero-browser directly to FuseBase Gate (
https://gate-mcp.thefusebase.com/mcp) and Dashboards (https://dashboards-mcp.thefusebase.com/mcp) with auto-discovered tenant identity, scopes, and default workspace. Token mode covers a subset of the tools (29 of 150 measured: workspaces, page/folder listing and creation, reading and appending content, database listing, isolated SQL stores, token management, operation discovery and triggering a configured automation). Most other named wrappers need a session cookie. See docs/TOKEN-COVERAGE.md.Advanced Markdown Ingestion: Automatic parsing of GFM tables into interactive
TableBlockobjects, markdown images (), GitHub callouts (> [!NOTE],> [!WARNING], etc.), HTML underline/highlight, and<details><summary>togglesAgent execution and extraction: Run AI Assistant agents and wait for completed streamed answers; request URL extraction through a configured scraping agent. Fetching depends on that agent, and the wrapper does not call Firecrawl directly. The legacy n8n-named tool routes through ActivePieces. These are separate from Gate's Paperclip Work-agent APIs.
Two-tier system — 34 core tools are exposed by default; switch to all 177 tools and back to core without restarting. Each change sends one tool-list notification; disabled tools cannot be invoked.
Token Economics & Markdown Conversion — retrieve page content as clean Markdown (
get_page_content(format: "markdown")) for ~50% token reduction via built-inhtmlToMarkdownconverterBinary Payload Safety & Native Images —
download_attachmentrenders images as native MCPimageblocks and streams large files directly to local disk (data/downloads/)Safety Annotations (
[DESTRUCTIVE]) — permanent deletion tools are explicitly tagged so AI clients and human supervisors can prompt for confirmationNative MCP Resources (8) —
fusebase://status,fusebase://workspaces,fusebase://guides/index,fusebase://work/connectors,fusebase://workspaces/{workspaceId}/pages/{pageId},fusebase://databases/{databaseId},fusebase://portals/{portalId}/clientsNative MCP Prompts (17) — pre-engineered workflow templates (
create-sop,summarize-page,build-kanban-project,design-automation-workflow,build-hosted-app,build-event-bridge,orchestrate-multi-agent-swarm,launch-client-portal,workspace-activity-digest,audit-page-governance,build-relational-database,import-knowledge-base,configure-ai-persona,crm-seed-demo-data,portal-embedded-app,fullstack-app-architecture,token-waste-audit)Official FuseBase CLI & Hosted Apps — inspect CLI status (
fusebase_cli_status), initialize products (fusebase_cli_init), list apps (fusebase_cli_list_apps), deploy Vite/React SPA apps to FuseBase Cloud (fusebase_cli_deploy), configure Docker sidecars (fusebase_cli_sidecar_add,fusebase_cli_sidecar_list,fusebase_cli_sidecar_remove), manage platform secrets (fusebase_cli_secret_create,fusebase_cli_secret_list), inspect remote logs (fusebase_cli_logs), and update app view permissions (fusebase_cli_app_update)Granular block mutations — non-destructive page block appending (
append_page_content) via real-time Y.js WebSocketsVibe Coding & Web Apps — generate interactive web app pages (
create_interactive_app_page) with responsive full-width embeds (allowOverWidth)ActivePieces Workflow Automation — flow inspection, creation, updating, deletion, trigger test runs (
trigger_automation_flow), and connector piece catalog with auto-managed JWT authenticationClient Portal "Hub" Platform — inspect availability (
check_portal_availability), create v2 portals (create_portal, requires a Gate token, full domain, and an unoccupied workspace; optional theme/access mode), retrieve branding/settings (get_portal), inspect themes and navigation, publish workspace pages, list portal clients, invite clients with explicitisFullAccess, and generate passwordless links for existing portal members. Invitations require Gate; separate link generation also uses the session cookie. Link creation does not establish email delivery or a fixed expiry.Multi-Agent Swarm Orchestrator — initialize shared state machine boards (
fusebase_swarm_init) and transition tasks across roles with audit history (fusebase_swarm_task_transition)Multi-Agent Profile Management — list and switch between encrypted credentials seamlessly (
list_agent_profiles,switch_active_profile)Database CRUD & View Templates — full kanban/table management: rows, columns, views, relations, managed templates (
get_dashboard_templates), CSV import/exportAuto auth retry — detects 401/403 and refreshes session automatically
Encrypted secrets — cookies stored encrypted at rest (AES-256-GCM)
Version checking — built-in update detection from GitHub
Live Cloud Status Dashboard — real-time engineering and validation status dashboard hosted directly on FuseBase Cloud at fusebase-mcp.thefusebase.app
API logging — all requests logged for debugging
🚀 Quick Start
Prerequisites
1. Install & Run
🤖 AI Coding Agents: See AGENTS.md and CLAUDE.md for optimized instructions on zero-context-clutter tool tiering and zero-browser token authentication.
Option A — Clone and build (recommended):
git clone https://github.com/ryan-haver/fusebase-mcp.git
cd fusebase-mcp
npm ci --ignore-scripts
npm run buildOption B — Install a built package:
Run npm pack in the checked-out source, then npm install -g ./fusebase-mcp-2.2.0.tgz.
The prepack step builds a clean distribution. The installed package includes fusebase-mcp,
fusebase-auth, and fusebase-guides; it does not compile source or download browsers during install.
Direct Git installs are not a supported prebuilt distribution path.
Download Chromium separately with npm run setup:browser for browser authentication.
Fetch reference guides explicitly with npm run guides:fetch (or installed fusebase-guides).
The Alpine container supports token mode; interactive browser authentication needs a supported host.
Option C — Docker (Zero-Install Container):
Run locally via Stdio (for Cursor, Claude Desktop):
docker run -i --rm \
-e FUSEBASE_GATE_TOKEN="your_token" \
-e FUSEBASE_DASHBOARDS_TOKEN="your_token" \
-e FUSEBASE_TOOLS="all" \
fusebase-mcp:latestOr run as a standing HTTP Network Server (for remote agents, swarms, and webhooks):
docker run -d --name fusebase-mcp -p 127.0.0.1:3000:3000 \
-e FUSEBASE_GATE_TOKEN="your_token" \
-e FUSEBASE_DASHBOARDS_TOKEN="your_token" \
-e MCP_TRANSPORT="http" \
-e MCP_HOST="0.0.0.0" \
-e MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
fusebase-mcp:latest
# Endpoint: http://localhost:3000/mcp (legacy SSE: /sse) | Health: /health
# Clients must send: Authorization: Bearer <MCP_AUTH_TOKEN>(Or set MCP_AUTH_TOKEN in .env and run docker compose up -d.)
Every HTTP session acts with your FuseBase credentials, so the server:
listens on
127.0.0.1unless--host/MCP_HOSTsays otherwise, and refuses a non-loopback address withoutMCP_AUTH_TOKEN;requires
Authorization: Bearer <MCP_AUTH_TOKEN>on every MCP request when a token is set;rejects unexpected
Hostheaders (extra names viaMCP_ALLOWED_HOSTS) and browserOrigins not listed inMCP_ALLOWED_ORIGINS.
2. Configure & Authenticate
FuseBase MCP provides three production authentication modes:
Named profiles use only their own encrypted cookies and tokens; they never inherit the default profile's environment credentials. Authenticate each named profile explicitly. For the default profile (including profile: "default"), environment credentials retain precedence over its encrypted store. The server uses one configured tenant; stored host/organization metadata, when present, must match FUSEBASE_HOST and FUSEBASE_ORG_ID.
┌──────────────────────────────────────────────────────────────────────────────────┐
│ Authentication Modes │
├───────────────────────┬──────────────────────────┬───────────────────────────────┤
│ Mode 1: Pure Token │ Mode 2: Session Cookie │ Mode 3: Hybrid (Recommended) │
│ (Zero-Browser / Gate) │ (Interactive / Headless) │ (Full-Spectrum Dual Engine) │
├───────────────────────┼──────────────────────────┼───────────────────────────────┤
│ • Official Gate MCP │ • Browser session cookie │ • Both token and cookie loaded│
│ • Official Dashboards │ • Interactive Chromium │ • Tokens for Gate operations │
│ • No browser needed │ • Y.js collaborative WS │ • Cookie for everything else │
│ • Auto whoami config │ • ActivePieces automations│• All 177 tools available │
└───────────────────────┴──────────────────────────┴───────────────────────────────┘Mode 1: Pure Token Mode (Direct Remote MCP Gateways — Zero-Browser)
Connect directly via official FuseBase Gate & Dashboards MCP gateways as specified in the official guides. Only part of the tool set works this way: tasks, comments, tags, members, page rename/move/delete, automations and most database and portal tools still need a session cookie (per-tool results: docs/TOKEN-COVERAGE.md).
Copy .env.example to .env:
cp .env.example .env# Direct Token Authentication (No cookies or browser needed)
FUSEBASE_GATE_TOKEN=your_gate_mcp_token
FUSEBASE_DASHBOARDS_TOKEN=your_dashboards_mcp_token
# or unified platform token:
# FUSEBASE_TOKEN=your_api_tokenZero Configuration: When tokens are provided, the server automatically connects to upstream Gate (
https://gate-mcp.thefusebase.com/mcp) and Dashboards (https://dashboards-mcp.thefusebase.com/mcp), auto-discovering your tenant organization ID (orgId), custom domain (FUSEBASE_HOST), and default workspace via upstreamwhoami.You can also save tokens securely encrypted at rest (AES-256-GCM):
npx tsx scripts/auth.ts --token <your_token> # or for named multi-agent profiles: npx tsx scripts/auth.ts --profile agent-architect --token <token>
Mode 2: Browser Session Cookie Mode (Interactive / Headless)
For direct Y.js CRDT WebSocket live synchronization and internal ActivePieces engine integration:
npx tsx scripts/auth.tsThis opens a browser window → log into Fusebase → cookies are automatically captured and saved encrypted (AES-256-GCM) to data/cookie.enc.
Headless mode: After initial login, you can re-authenticate without a browser window:
npx tsx scripts/auth.ts --headlessMulti-Agent Profiles: Authenticate a specific named profile:
npx tsx scripts/auth.ts --profile agent-architect
Mode 3: Hybrid Mode (Recommended for Full-Spectrum Agents)
Supply both tokens (FUSEBASE_GATE_TOKEN, FUSEBASE_DASHBOARDS_TOKEN) and a session cookie (FUSEBASE_COOKIE or data/cookie.enc). The server intelligently routes:
Gate & Dashboards MCP: Uses high-speed Bearer tokens for tenant discovery, isolated PostgreSQL stores, databases, and token management.
Notes Engine Fallback: Automatically serves note/page/folder CRUD via Gate when session cookie is absent, and leverages real-time Y.js CRDT WebSocket sync when cookies are present.
Automation Engine: Exchanges session cookie for ActivePieces project JWTs while allowing external webhook triggers via FuseBase Work.
3. Authentication Modes Feature Parity & Empirical Comparison
Most named wrappers need a session cookie today: with only Gate and Dashboards tokens, 29 of 150 measured remote tools work (2026-11-03 UTC); 121 require cookies. Both automation trigger tools now have proof of completed execution and expected outputs. Per-tool results are in docs/TOKEN-COVERAGE.md, with broader live results and exclusions in docs/LIVE-VALIDATION.md.
The table below compares the core capabilities in both modes, measured by npm run test:parity (tests/live/token-parity.ts) against live FuseBase:
Domain | Feature | Pure Token Mode | Cookie / Session Mode | Parity Category | Technical Notes |
Identity | Gate Tenant Identity ( | ✅ PASS | ➖ N/A | Token Superpower | Gate resolves |
Identity | Session Org Usage & Quotas | ➖ N/A | ✅ PASS | Full Parity | Both modes provide full identity resolution; session cookies query |
Workspaces | List Workspaces ( | ✅ PASS | ✅ PASS | Full Parity | Pure Token maps Gate |
Pages & Notes | List Pages ( | ✅ PASS | ✅ PASS | Full Parity | Pure Token uses Gate |
Pages & Notes | Create Page ( | ✅ PASS | ✅ PASS | Full Parity | Pure Token uses Gate |
Pages & Notes | Read Page Content ( | ✅ PASS | ✅ PASS | Full Parity | Pure Token reads Markdown via Gate |
Pages & Notes | Append Page Content ( | ✅ PASS | ✅ PASS | Full Parity | Pure Token uses Gate |
Folders | Folder List & Create ( | ✅ PASS | ✅ PASS | Full Parity | Pure Token calls Gate |
Databases | Database Discovery ( | ✅ PASS | ✅ PASS | Full Parity | Pure Token queries Dashboards MCP |
Isolated Stores | PostgreSQL Control & Migrations | ✅ PASS | ➖ N/A | Token Superpower | Exclusive to Gate MCP Bearer Token ( |
Token Lifecycle | Programmatic Token Creation & Revocation | ✅ PASS | ➖ N/A | Token Superpower | Exclusive to Gate MCP: Programmatic API token generation, revocation, and catalog inspection ( |
CRDT Collaboration | Live Y.js WebSocket Sync ( | 🔒 RESTRICTED | ✅ PASS | Cookie Exclusive | Y.js collaborative gateway validates |
Automations | ActivePieces Internal Engine ( | 🔒 RESTRICTED | ✅ PASS | Cookie Exclusive | Internal ActivePieces auth exchanges |
Binary Files | Web Editor Multipart Uploads ( | 🔒 RESTRICTED | ✅ PASS | Cookie Exclusive | Legacy web editor file upload multipart handler validates browser session state. (See Architectural Note 3) |
UI State | Sidebar collapse & Web UI Preferences | 🔒 RESTRICTED | ✅ PASS | Cookie Exclusive | UI state toggles are stored in user session variables ( |
Architectural Notes on Cookie-Dependent Services
Real-time Y.js CRDT Collaborative WebSocket Sync (
wss://text.nimbusweb.me):
The real-time collaborative editing service uses Y.js binary sync protocols over WebSockets. The WebSocket handshake endpoint validates theeversessionidcookie header during HTTP upgrade and rejects unauthenticated or bearer-token-only connections with HTTP 401. In Pure Token Mode, the client automatically routes page content reads and appends through Gate MCP (getWorkspaceNoteandappendWorkspaceNoteContent), so pages can be listed, read, created and appended to without a WebSocket connection. Replacing content, embeds, renaming, moving and deleting pages still need the cookie.Internal ActivePieces Workflow Engine (
/automation/api/v1/...):
FuseBase's embedded ActivePieces automation platform relies on an authentication bridge (/automation/api/v1/authentication/fusebase-auth) that requires an activeeversessionidcookie to mint a temporary project JWT and resolve the tenant's automationprojectId. In Pure Token Mode, external automations can be triggered via FuseBase Work connectors (fusebase_work_trigger_n8nor webhook endpoints) without invoking the internal ActivePieces session bridge.Legacy Web Editor Multi-Part File Uploads (
/v3/api/web-editor/file/v2-upload):
The legacy web editor attachment route specifically checks for browser session cookies in multi-part form submissions. File downloads, asset links, and URL-based attachments operate without restrictions across all modes, while raw binary uploads through the legacy editor form route require a session cookie.Web UI State & Session Preferences:
Preferences likeset_sidebar_collapsedand last-opened workspace lists exist only in the web client's session state variables (/v2/api/users/vars/...). Because headless AI agents interact programmatically via MCP tools rather than a visual UI layout, this restriction does not affect automation workflows.
Operational Recommendation: Which Mode Should You Use?
Use Pure Token Mode (
FUSEBASE_GATE_TOKEN+FUSEBASE_DASHBOARDS_TOKEN):
Best for CI/CD pipelines, autonomous Docker containers, headless cloud workers, and multi-tenant AI agents where browser login is impossible or undesirable. Covers workspaces, page and folder listing and creation, reading and appending page content, database listing and isolated SQL stores, with no browser. Most other tools need a session cookie today; see docs/TOKEN-COVERAGE.md before relying on it.Use Hybrid Mode (Tokens + Cached Cookie):
Best for local developer environments, rich interactive pair programming, and full-spectrum swarm orchestration where live Y.js WebSocket document collaboration and ActivePieces workflow creation are utilized alongside Gate MCP's PostgreSQL stores.
4. Connect to Your AI Assistant (Claude, Cursor, Antigravity, Codex, OpenCode)
Single-System Credential Architecture
FuseBase MCP is built for multi-agent environments sharing a single machine. Once you configure credentials on your machine (via .env, npx tsx scripts/auth.ts --token <token>, or browser login):
Zero-Config Agent Discovery: Any coding agent running
node dist/index.jsin the workspace root automatically reads the local encrypted credentials and connects immediately without needing tokens or cookies hardcoded in the agent's JSON config.Multi-Agent Profile Isolation: When running multi-agent swarms (e.g. PM, Architect, Developer, QA), each agent can use its own distinct encrypted identity simply by setting
"FUSEBASE_PROFILE": "agent-architect".Docker Execution: For containers or remote runners, you can pass
FUSEBASE_GATE_TOKENandFUSEBASE_DASHBOARDS_TOKENdirectly in the containerenvblock.
Client Configuration Templates
Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"fusebase": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"FUSEBASE_TOOLS": "all"
}
}
}
}Or via Docker (Zero-Install):
{
"mcpServers": {
"fusebase": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "FUSEBASE_GATE_TOKEN",
"-e", "FUSEBASE_DASHBOARDS_TOKEN",
"-e", "FUSEBASE_TOOLS=all",
"fusebase-mcp:latest"
]
}
}
}Claude Code CLI:
# Add as a local plugin using native .claude-plugin/plugin.json
claude plugin add .Or run directly via stdio:
claude mcp add fusebase -- node dist/index.jsIn your workspace root, create or edit .cursor/mcp.json (or add via Cursor Settings > Features > MCP):
{
"mcpServers": {
"fusebase": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"FUSEBASE_TOOLS": "all"
}
}
}
}Or via Docker:
{
"mcpServers": {
"fusebase": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "FUSEBASE_GATE_TOKEN",
"-e", "FUSEBASE_DASHBOARDS_TOKEN",
"-e", "FUSEBASE_TOOLS=all",
"fusebase-mcp:latest"
]
}
}
}Add to your global Antigravity MCP configuration or workspace .agent/mcp_config.json:
{
"mcpServers": {
"fusebase": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"FUSEBASE_TOOLS": "all"
}
}
}
}This repository includes native .codex-plugin/plugin.json for OpenAI Codex agent ecosystems.
Add via Codex CLI:
codex mcp add fusebase --command node --args dist/index.jsOr in your Codex configuration:
{
"mcp": {
"fusebase": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"FUSEBASE_TOOLS": "all"
}
}
}
}OpenCode supports local stdio execution, Docker, and direct upstream HTTP Gate connection:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"fusebase": {
"type": "stdio",
"command": "node",
"args": ["dist/index.js"],
"env": {
"FUSEBASE_TOOLS": "all"
}
}
}
}{
"mcp": {
"servers": {
"fusebase": {
"command": "node",
"args": ["dist/index.js"],
"env": {
"FUSEBASE_TOOLS": "all"
}
}
}
}
}Note: If running outside the repository root directory, you can specify the full path to
dist/index.jsor use${workspaceFolder}/dist/index.js. If credentials are saved in.envordata/tokens.enc, no auth environment variables are required in the client JSON!
5. Verify
Ask your AI assistant:
"List my Fusebase workspaces"
If it works, you're all set! 🎉
You can also run automated verification directly from your terminal:
npm test # Offline unit tests (no credentials needed)
npm run test:all -- --offline # Typecheck, lint, build, unit tests, schema audit (what CI runs)
npm run test:live # Live suites against your sandbox workspace (see below)
npm run deploy:status # Build & deploy live status dashboard to fusebase-mcp.thefusebase.app
npm run deploy:page # Embed the live status dashboard into a FuseBase workspace noteSandbox Workspace for Live Tests
Live test suites create and delete pages, folders, databases and flows, so they only run in a workspace you name explicitly. There is no fallback to "the first workspace":
Environment variable (recommended): set
FUSEBASE_WORKSPACE_IDin your.envCLI flag:
npm run test:data-validation -- --workspace=<workspace-id>
Portal invite / magic-link checks require FUSEBASE_TEST_SEND_EMAIL=1, FUSEBASE_TEST_INVITE_EMAIL set to an address you control, and an explicit FUSEBASE_TEST_CLIENT_FULL_ACCESS=true|false. API success does not confirm inbox delivery or link activation. Existing non-client organization roles are protected from client-role changes.
npm run deploy:page accepts the same --workspace=<id|name> flag and FUSEBASE_WORKSPACE_ID.
📚 Native MCP Resources & Prompts
FuseBase MCP supports first-class MCP protocol primitives for zero-overhead context injection:
Resources (fusebase://)
Clients can attach FuseBase data directly into their context window:
URI Pattern | Type | Description |
| Static | Tool counts by tier and the status dashboard URL |
| Static | JSON array of all accessible workspaces |
| Static | Comprehensive index of all 278 FuseBase documentation guides |
| Static | Catalog of integrated third-party services and automation connectors |
| Template | Full markdown content of any specific guide |
| Template | Decoded HTML representation of any page (also supports legacy |
| Template | Complete JSON schema and views for a database (also supports legacy |
| Template | List of invited external clients and permissions for a portal |
Pre-Engineered Prompts (17)
Quick-start workflow prompts available to AI clients:
create-sop: Guides the assistant in generating a rigorous Standard Operating Procedure document with scope, prerequisites, step-by-step procedures, and verification checklists.summarize-page: Fetches living page content viagetPageContentand synthesizes an executive summary, key decisions, prioritized action items, and open questions.build-kanban-project: Guides the AI to design a structured project board with customized column flows, custom field recommendations, and starter cards.design-automation-workflow: Prompts the design of an ActivePieces automation workflow mapping triggers, action steps, retry policies, and error handling.build-hosted-app: Architects a full-stack FuseBase Web App covering frontend UI tokens, backend data, CLI commands, and responsive embedding.build-event-bridge: Designs bidirectional webhook bridges connecting external systems (Stripe, GitHub, n8n) into FuseBase and triggering workflows viatrigger_automation_flow.orchestrate-multi-agent-swarm: Decomposes complex initiatives into coordinated multi-agent swarms tracked through FuseBase Kanban boards (fusebase_swarm_init,fusebase_swarm_task_transition).launch-client-portal: Plans and provisions an external branded Client Portal with custom theme, sidebar navigation hierarchy, page publication matrix, and passwordless magic link invitations (invite_portal_client,create_portal_magic_link).workspace-activity-digest: Ingests recent workspace activity, updated pages, and task completion metrics to produce an executive velocity pulse and blocker digest.audit-page-governance: Fetches page content and audits heading hierarchy (H1-H3), incomplete action items (- [ ]), stale dates, and tags, providing a concrete revision plan.build-relational-database: Architects a multi-table relational schema with bidirectional relations (add_relation_column), lookup rollups (add_lookup_column), and specialized Kanban/Grid views.import-knowledge-base: Plans structured migrations of Notion workspaces, Confluence spaces, or CSV datasets into FuseBase folders, markdown pages, and databases.configure-ai-persona: Designs specialized AI assistant personas with tailored charters, quick-action suggestion chips, and starter conversation threads.crm-seed-demo-data: Generates high-fidelity CRM demo records (Companies, Contacts, Deals table/pipeline, Trackers) with relational integrity across parent and child tables.portal-embedded-app: Guides scaffolding and deployment of FuseBase client portal embedded applications using dynamic{{CurrentPortal}}view filtering and runtime context authentication.fullstack-app-architecture: Architects enterprise full-stack FuseBase Web Applications with Docker sidecar microservices, secret whitelisting, and unified localhost routing.token-waste-audit: Audits active agent interactions and tool invocations to identify redundant schema fetching, enforce compact Markdown formats, and recover context bandwidth.
🔧 Tool Tiers
The server uses a core/extended tier system to optimize agent context usage:
Tier | Tools | Description |
Core (default) | 34 | Day-to-day: full CRUD and organization for pages, folders, content, tasks, tags, attachments, members, guides, session health, profiles |
Extended | +143 | Admin, CLI apps, automations, portal lifecycle, databases, relations, batch mutations, isolated SQL stores, Gate tokens, templates, swarm state machines, billing, preferences |
Enable extended tools:
Mid-session: ask your AI to use
set_tool_tierwithtier: "all"Always-on: add
FUSEBASE_TOOLS=allto your.env
Core Tools (34)
Core tools load by default and provide complete CRUD and organization operations for day-to-day workspace workflows without requiring extended tier switching:
Category | Tool | Description |
Meta |
| Enable extended tools ( |
Meta |
| Check for server updates from GitHub |
Auth |
| Refresh session cookies via Playwright |
Auth |
| Inspect cookie age, profile metadata, and test API connectivity |
Profiles |
| List all configured encrypted agent credential profiles |
Profiles |
| Switch active agent session profile dynamically |
Content |
| List all accessible workspaces |
Content |
| List pages (filter by folder/parentId, pagination) |
Content |
| Get page metadata and properties |
Content |
| Recently accessed pages in workspace |
Content |
| Create a page with optional markdown or block content |
Content |
| Update page title or move between folders |
Content |
| Move a page between folders or migrate across workspaces |
Content |
|
|
Content |
| Retrieve page content as HTML or token-efficient Markdown ( |
Content |
| Non-destructive block append via real-time Y.js WebSocket |
Content |
| Full document content overwrite via Y.js |
Content |
| Workspace folder hierarchy |
Content |
| Create a new folder |
Tasks |
| Search tasks across workspace |
Tasks |
| List task boards/lists |
Tasks |
| Create a new task |
Tasks |
| Update task properties, title, or completion status |
Tasks |
|
|
Tags |
| List workspace tags |
Tags |
| Set tags on a page |
Files |
| List attachments on a page |
Files |
| Upload file attachment to a page |
Files |
| List uploaded files |
Files |
| Download attachment (native MCP |
Members |
| List workspace members |
Guides |
| Search 278 FuseBase guides by keyword |
Guides |
| Get full markdown guide by section and slug |
Guides |
| Browse all 19 documentation sections |
Extended Tools (134)
Enable with set_tool_tier(tier: "all") or set FUSEBASE_TOOLS=all in .env:
FuseBase Work (Firecrawl & n8n):
fusebase_work_run_agent,fusebase_work_scrape_url,fusebase_work_trigger_n8nClient Portal Hub:
check_portal_availability,create_portal,get_portal,get_portal_theme,get_portal_navigation_menu,get_workspace_portal,publish_page_to_portal,list_portal_clients,invite_portal_client,create_portal_magic_link,list_portals,get_portal_pagesMulti-Agent Swarms:
fusebase_swarm_init,fusebase_swarm_task_transitionFuseBase CLI & Hosted Apps:
fusebase_cli_status,fusebase_cli_init,fusebase_cli_list_apps,fusebase_cli_deploy,fusebase_cli_sidecar_add,fusebase_cli_sidecar_list,fusebase_cli_sidecar_remove,fusebase_cli_secret_create,fusebase_cli_secret_list,fusebase_cli_logs,fusebase_cli_app_update,create_interactive_app_pageActivePieces Workflow Automations:
list_automation_flows,get_automation_flow,create_automation_flow,update_automation_flow,delete_automation_flow,trigger_automation_flow,list_flow_runs,list_automation_pieces,get_automation_flags,list_automation_folders,create_automation_folder,delete_automation_folder,get_automation_userTasks (Metrics & Logs):
get_tasks_workspace_summary,get_task_time_tracking,get_task_description,get_task_count,get_task_usageLabels & Tags:
get_labels,get_note_tagsComments & Activity Stream:
get_activity_stream,get_comment_threads,fusebase_poll_mentions,fusebase_post_comment,fusebase_reply_comment,fusebase_resolve_threadFiles & Storage:
get_file_countOrganization Administration:
get_member_roles,get_workspace_members_v1,get_org_trials,get_org_usage,get_org_limits,get_usage_summary,get_org_permissions,get_org_features,get_ai_usageWorkspaces & Subscription:
get_workspace_premium_status,get_active_import_status,get_workspace_detail,get_workspace_emails,get_workspace_infoNavigation & AI Assistant:
get_agent_public_profile,get_ai_assistant_state,list_ai_agent_threads,get_ai_agent_favorites,get_navigation_menu,get_mention_entities,list_agents,list_ai_agent_categories,get_recently_updated_notesDatabases & Tables:
get_dashboard_templates,get_database_entity_templates,get_database_data,list_databases,get_database_entity,create_database,add_database_row,delete_database_row,move_kanban_card,list_database_relations,create_dashboard_table,delete_relation,list_all_databases,get_database_detail,update_database,delete_database,get_dashboard_detail,delete_dashboard,batch_put_database_data,resolve_database_aliasViews:
update_view,set_view_representation,create_view,delete_view,duplicate_view,set_view_groupingColumns:
add_database_column,delete_database_column,rename_database_column,reorder_database_columns,set_column_width,add_relation_column,add_lookup_columnCells & Rows:
update_database_cell,get_database_rows,get_database_schema,reorder_database_rowsDirect Gate & Dashboards Tokens:
fusebase_token_list,fusebase_token_create,fusebase_token_get,fusebase_token_revoke,fusebase_token_permission_catalog,fusebase_gate_whoami,fusebase_discover_operations,fusebase_direct_tool_callCLI updates:
fusebase_cli_updatepreviews the official update by default. SetdryRun: falseto apply;includeProduct: truealso refreshes managed product assets, MCP configuration and dependencies. Git checkpoints are disabled.fusebase_cli_app_updatesupports access principals, additive Gate permission sync, and named environments; build settings belong infusebase.json.
Following upstream API additions
Enable the extended tier, then call fusebase_discover_operations with query and target to find current operations. Supply an opId to inspect its input schema, or schemaMode: "both" for input/output schemas. Fetch the returned requiredPrompts.groups with promptGroups before calling that operation. Use fusebase_direct_tool_call with applyDefaults: false to preserve the exact argument contract (including strict operations that reject extra orgId fields).
Discovery is filtered and paginated; it does not register every upstream schema in your agent's context. New upstream features remain subject to your token's permissions and platform rollout. See the November 2026 compatibility review for verified versions, available additions, and remaining gaps.
Row-Level Relations:
link_database_rows,unlink_database_rows,get_relation_rowsGate PostgreSQL Isolated SQL Stores:
list_isolated_stores,create_isolated_store,query_isolated_sql,execute_isolated_sql,select_isolated_sql_rows,insert_isolated_sql_row,batch_insert_isolated_sql_rows,list_isolated_sql_tables,apply_isolated_sql_migrationsBilling & User Preferences:
get_billing_info,get_user_preferences,set_sidebar_collapsedImport/Export:
duplicate_database,export_csv,import_csv
🔐 Security
Encrypted at rest — saved cookies, tokens and agent credentials are encrypted with AES-256-GCM using a random key in
data/.key(owner-only) orFUSEBASE_SECRET_KEY1Password — keep tokens and
FUSEBASE_SECRET_KEYin 1Password, put onlyop://references in.env, and start the server withop run --env-file=.env -- node dist/index.js. Vault items or a 1Password Environment both work. See docs/1PASSWORD.mdAuto-refresh — expired sessions are transparently refreshed via Playwright
.envis gitignored — credentials never enter version controlCookie via env var — optionally pass
FUSEBASE_COOKIEin your MCP config for environments where the encrypted store isn't available
🗂️ Project Structure
src/
index.ts → Entry point: loads configuration, starts stdio or HTTP transport
server.ts → Builds one MCP server per session (tools, resources, prompts, tier switching)
http-server.ts → Streamable HTTP (+ legacy SSE) transport with bearer auth and Host/Origin checks
config.ts → .env, 1Password Environment and op:// reference loading; token resolution
secret-refs.ts → 1Password integration (op read, SDK Environment loading)
client.ts → FuseBase web API client (one request path: auth, timeouts, refresh, logging)
client-factory.ts → Builds clients per profile; caches Gate bridges per token set
gate-bridge.ts → Client for the official Gate & Dashboards MCP endpoints
write-safety.ts → When a failed write may be retried on another path
crypto.ts → Encrypted credential store (random key, legacy migration)
yjs-ws-writer.ts → Y.js WebSocket writer/reader for page content (confirmed writes)
yjs-html-decoder.ts → Y.js document → HTML / markdown
markdown-parser.ts → Markdown (mdast + GFM) → content blocks
content-schema.ts → Content block types
resources.ts, prompts.ts → MCP resources and prompts
guide-loader.ts → Search over the downloaded FuseBase guides
cli-manager.ts, proxy-relay.ts, ids.ts, types.ts
tools/ → Tool definitions (core and extended tiers)
tests/
unit/ → Offline unit tests (vitest), run by CI and the pre-commit hook
live/ → Live suites against a sandbox workspace; every write proven by a read (docs/TESTING.md)
lib/harness.ts → Live-suite harness: strict tool calls, write verification, skips, exit codes
sweep-sandbox.ts → Leftover sweep run after the live suites
scripts/
test-all.ts → Runs the offline stages and/or the live suites (`npm run test:all`)
audit-tools.ts → Tool schema, duplicate and README coverage audit
auth.ts → Capture/refresh session cookies with a browser (`npm run setup:browser` first)
check-1password.ts → Shows where each secret comes from (names only)
scrape-guides.ts → Downloads the FuseBase guides (`npm run guides:fetch`)
deploy-status-dashboard.ts → Builds and deploys the status dashboard app
docs/ → Testing, 1Password, remediation plan and design notes
apps/ → The status dashboard FuseBase app
.githooks/ → Commit and push validation gate (`npm run hooks:install`)
.cache/guides/ → (gitignored) Downloaded FuseBase guides
data/ → (gitignored) Encrypted credentials, browser profiles, downloads, logs🗺️ Roadmap & Implemented Milestones
See ENDPOINT_REFERENCE.md for all discovered and implemented API endpoints.
Completed Milestones
Core Tier CRUD Completeness — 34 core tools providing full CRUD for pages, folders, content, tasks, and files.
ActivePieces Workflow Automation — Flow creation, updates, triggers, piece catalog, and JWT exchange.
Client Portal Hub Lifecycle — Portal creation, domain lookup, theme inspection, client permissions, and magic links.
Multi-Agent Swarm Orchestration — Collaborative Kanban state machines with role transitions.
Native AI Assistant & Agent Threads — AI suggestions, threads, and user preferences.
Token Economics & Binary Safety — HTML-to-Markdown conversion and native image / local disk file staging.
RFC 6570 Resource Templates & Prompts — Direct URI data mounting and pre-engineered workflows.
Write-Verified Live Testing — every write the live suites make is proven by a fresh read; a leftover sweep checks the sandbox; commits and pushes are gated on the checks.
Token-Only Coverage Measured — per-tool results in docs/TOKEN-COVERAGE.md.
Future Opportunities
Bidirectional Webhook Listeners — Local webhook listener bridge for real-time external event triggers into FuseBase.
Offline Working Memory — Local SQLite caching adapter for instant retrieval of high-frequency pages and database schemas.
🧪 Testing & Validation
The November 3 project review and remediation plan records current findings, verification limits, and prioritized acceptance criteria.
Tests are split into offline checks (fast, no credentials, run in CI) and live suites (talk to FuseBase, run locally against a sandbox workspace).
npm test # Offline unit tests (vitest), tests/unit/
npm run typecheck # Typecheck src, scripts and tests
npm run lint # ESLint
npm run test:all -- --offline # All offline stages (same as CI)
npm run test:live # All live suites (needs credentials + FUSEBASE_WORKSPACE_ID)
npm run test:all # Offline stages, then live suitesCommand | What it checks |
| Offline unit tests: markdown parser, Y.js writer → decoder round trips, tool registry and tiers, input validation, path handling, CLI argument building, server process behaviour |
| Every tool has a description and described parameters, no duplicate tools, every tool documented in README.md |
| Gate/Dashboards token identity, permission catalog, token list, isolated stores |
| MCP resources, prompts, tier switching and a full page lifecycle over stdio |
| Every block type and inline format written over the Y.js WebSocket and read back |
| Database, column, row, view, relation, CSV and cloning lifecycle |
| Disposable flow configuration, publication, two distinct executions with verified outputs, and cleanup |
| Explicit account-wide preference restore and persisted browser-auth refresh checks |
| Live calls across the tool catalog with data-shape and round-trip assertions |
| The same capabilities measured in token mode and cookie mode |
How results are reported. Suites exit non-zero on any failure. Capabilities an org may legitimately lack (CLI not installed, feature not on the plan) are reported as explicit skips, never as passes. Behaviour that is known to be broken is tracked as an expected failure (it.fails offline, knownGap() live) tagged with its finding ID from docs/PLAN-review-remediation.md; when a fix lands, the marker turns red until it is removed.
Before You Push
npm run test:all -- --offline(CI includes exact Node 22.19.0 on Linux/Windows, Node 24/26, package, dashboard, container, audit and secret checks)npm run test:livefor any change that touches API calls, content writing or authnpm run deploy:statusif you maintain the status dashboard
🤝 Contributing
Fork the repo
Create a feature branch
Run
npm run buildto verify TypeScript compilesSubmit a PR
📄 License
MIT
Review remediation and release evidence
See the current review and validation instructions.
HTTP sessions expire after 15 idle minutes (MCP_SESSION_IDLE_MS); invalid session limits fail startup.
Runtime logs, namespaced caches, credentials and default downloads honor FUSEBASE_DATA_DIR.
Logs retain two bounded files. Named profiles never inherit default credentials.
Deployment is explicit after push: npm run deploy:status. It requires a clean pushed source tree,
passing current offline evidence, and an exact live release.json match. A 200 response alone is insufficient.
Committing or pushing does not deploy the dashboard.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Manage tasks, projects, roadmaps, files, meetings, and team workflows with AI tools.
Give your AI agent 75+ business tools: tasks, projects, CRM, forms, E-Sign, team comms, automations.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables AI assistants to interact with ProjectHub for comprehensive project management through natural language. It provides 25 tools to manage tasks, workspaces, time tracking, notes, and discussions via the ProjectHub API.4713 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with the Fizzy task management tool through 40 specialized tools for managing boards, cards, and comments. It supports comprehensive task operations including card creation, triaging, and user assignments with built-in retry logic and secure authentication.24 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage ClickUp workspaces, teams, spaces, folders, lists, tasks, and custom fields via 29 MCP tools with full CRUD operations.5ISC
- AlicenseNot gradedqualityDmaintenanceProvides AI assistants with full read/write access to AppFlowy Cloud, enabling management of workspaces, pages, databases, trash, and favorites, plus conversion of Markdown into formatted AppFlowy document blocks.MIT