Skip to main content
Glama

FuseBase MCP Server

Version Live Status Dashboard MCP Tools Offline Checks Docker Ready Token-only coverage Write-verified live tests

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 TableBlock objects, markdown images (![alt](url)), GitHub callouts (> [!NOTE], > [!WARNING], etc.), HTML underline/highlight, and <details><summary> toggles

  • Agent 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-in htmlToMarkdown converter

  • Binary Payload Safety & Native Images — download_attachment renders images as native MCP image blocks 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 confirmation

  • Native MCP Resources (8) — fusebase://status, fusebase://workspaces, fusebase://guides/index, fusebase://work/connectors, fusebase://workspaces/{workspaceId}/pages/{pageId}, fusebase://databases/{databaseId}, fusebase://portals/{portalId}/clients

  • Native 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 WebSockets

  • Vibe 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 authentication

  • Client 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 explicit isFullAccess, 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/export

  • Auto 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 build

Option 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:latest

Or 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.1 unless --host / MCP_HOST says otherwise, and refuses a non-loopback address without MCP_AUTH_TOKEN;

  • requires Authorization: Bearer <MCP_AUTH_TOKEN> on every MCP request when a token is set;

  • rejects unexpected Host headers (extra names via MCP_ALLOWED_HOSTS) and browser Origins not listed in MCP_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_token

Zero 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 upstream whoami.

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>

For direct Y.js CRDT WebSocket live synchronization and internal ActivePieces engine integration:

npx tsx scripts/auth.ts

This 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 --headless

Multi-Agent Profiles: Authenticate a specific named profile:

npx tsx scripts/auth.ts --profile agent-architect

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 (whoami)

✅ PASS

➖ N/A

Token Superpower

Gate resolves orgId, domain, user ID, default workspace, and granted permissions with zero browser login.

Identity

Session Org Usage & Quotas

➖ N/A

✅ PASS

Full Parity

Both modes provide full identity resolution; session cookies query /gwapi2/ft:tasks/workspace-infos.

Workspaces

List Workspaces (list_workspaces)

✅ PASS

✅ PASS

Full Parity

Pure Token maps Gate listWorkspaces; Cookie queries task workspace infos. Both yield real workspace IDs and roles.

Pages & Notes

List Pages (list_pages)

✅ PASS

✅ PASS

Full Parity

Pure Token uses Gate listWorkspaceNotes; Cookie uses /v2/api/workspaces/{wid}/notes.

Pages & Notes

Create Page (create_page)

✅ PASS

✅ PASS

Full Parity

Pure Token uses Gate createWorkspaceNote; Cookie uses /v2/api/web-editor/notes/create.

Pages & Notes

Read Page Content (get_page_content)

✅ PASS

✅ PASS

Full Parity

Pure Token reads Markdown via Gate getWorkspaceNote; Cookie syncs HTML via Y.js WebSocket decoder.

Pages & Notes

Append Page Content (append_page_content)

✅ PASS

✅ PASS

Full Parity

Pure Token uses Gate appendWorkspaceNoteContent; Cookie syncs delta blocks via Y.js WebSocket writer.

Folders

Folder List & Create (list_folders, create_folder)

✅ PASS

✅ PASS

Full Parity

Pure Token calls Gate listWorkspaceNoteFolders & createWorkspaceNoteFolder; Cookie calls /gwapi2/ft:notes/menu.

Databases

Database Discovery (list_databases)

✅ PASS

✅ PASS

Full Parity

Pure Token queries Dashboards MCP getAllDatabases; Cookie queries /v1/dashboards/databases. Schemas, rows, views and relations need the cookie today (see TOKEN-COVERAGE.md).

Isolated Stores

PostgreSQL Control & Migrations

✅ PASS

➖ N/A

Token Superpower

Exclusive to Gate MCP Bearer Token (listIsolatedStores, queryIsolatedSql, apply migrations).

Token Lifecycle

Programmatic Token Creation & Revocation

✅ PASS

➖ N/A

Token Superpower

Exclusive to Gate MCP: Programmatic API token generation, revocation, and catalog inspection (listTokens, createToken).

CRDT Collaboration

Live Y.js WebSocket Sync (wss://text.nimbusweb.me)

🔒 RESTRICTED

✅ PASS

Cookie Exclusive

Y.js collaborative gateway validates eversessionid during HTTP WebSocket upgrade. (See Architectural Note 1)

Automations

ActivePieces Internal Engine (/automation/api/v1/...)

🔒 RESTRICTED

✅ PASS

Cookie Exclusive

Internal ActivePieces auth exchanges eversessionid for project JWT. (See Architectural Note 2)

Binary Files

Web Editor Multipart Uploads (/v3/api/web-editor/...)

🔒 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 (/v2/api/users/vars/...). (See Architectural Note 4)

  1. 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 the eversessionid cookie 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 (getWorkspaceNote and appendWorkspaceNoteContent), 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.

  2. 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 active eversessionid cookie to mint a temporary project JWT and resolve the tenant's automation projectId. In Pure Token Mode, external automations can be triggered via FuseBase Work connectors (fusebase_work_trigger_n8n or webhook endpoints) without invoking the internal ActivePieces session bridge.

  3. 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.

  4. Web UI State & Session Preferences:
    Preferences like set_sidebar_collapsed and 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):

  1. Zero-Config Agent Discovery: Any coding agent running node dist/index.js in the workspace root automatically reads the local encrypted credentials and connects immediately without needing tokens or cookies hardcoded in the agent's JSON config.

  2. 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".

  3. Docker Execution: For containers or remote runners, you can pass FUSEBASE_GATE_TOKEN and FUSEBASE_DASHBOARDS_TOKEN directly in the container env block.


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.js

In 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.js

Or 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.js or use ${workspaceFolder}/dist/index.js. If credentials are saved in .env or data/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 note

Sandbox 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_ID in your .env

  • CLI 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

fusebase://status

Static

Tool counts by tier and the status dashboard URL

fusebase://workspaces

Static

JSON array of all accessible workspaces

fusebase://guides/index

Static

Comprehensive index of all 278 FuseBase documentation guides

fusebase://work/connectors

Static

Catalog of integrated third-party services and automation connectors

fusebase://guides/{section}/{slug}

Template

Full markdown content of any specific guide

fusebase://workspaces/{workspaceId}/pages/{pageId}

Template

Decoded HTML representation of any page (also supports legacy {wid}/{nid})

fusebase://databases/{databaseId}

Template

Complete JSON schema and views for a database (also supports legacy {did})

fusebase://portals/{portalId}/clients

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 via getPageContent and 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 via trigger_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_tier with tier: "all"

  • Always-on: add FUSEBASE_TOOLS=all to 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

set_tool_tier

Enable extended tools (tier: "all") or check active tier

Meta

check_version

Check for server updates from GitHub

Auth

refresh_auth

Refresh session cookies via Playwright

Auth

check_session_health

Inspect cookie age, profile metadata, and test API connectivity

Profiles

list_agent_profiles

List all configured encrypted agent credential profiles

Profiles

switch_active_profile

Switch active agent session profile dynamically

Content

list_workspaces

List all accessible workspaces

Content

list_pages

List pages (filter by folder/parentId, pagination)

Content

get_page

Get page metadata and properties

Content

get_recent_pages

Recently accessed pages in workspace

Content

create_page

Create a page with optional markdown or block content

Content

update_page

Update page title or move between folders

Content

move_page

Move a page between folders or migrate across workspaces

Content

delete_page

[DESTRUCTIVE] Delete a page permanently

Content

get_page_content

Retrieve page content as HTML or token-efficient Markdown (format: "markdown")

Content

append_page_content

Non-destructive block append via real-time Y.js WebSocket

Content

update_page_content

Full document content overwrite via Y.js

Content

list_folders

Workspace folder hierarchy

Content

create_folder

Create a new folder

Tasks

search_tasks

Search tasks across workspace

Tasks

list_task_lists

List task boards/lists

Tasks

create_task

Create a new task

Tasks

update_task

Update task properties, title, or completion status

Tasks

delete_task

[DESTRUCTIVE] Delete a task permanently

Tags

get_tags

List workspace tags

Tags

update_page_tags

Set tags on a page

Files

get_page_attachments

List attachments on a page

Files

upload_file

Upload file attachment to a page

Files

list_files

List uploaded files

Files

download_attachment

Download attachment (native MCP image block or direct disk save to data/downloads/)

Members

get_members

List workspace members

Guides

search_guides

Search 278 FuseBase guides by keyword

Guides

get_guide

Get full markdown guide by section and slug

Guides

list_guide_sections

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_n8n

  • Client 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_pages

  • Multi-Agent Swarms: fusebase_swarm_init, fusebase_swarm_task_transition

  • FuseBase 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_page

  • ActivePieces 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_user

  • Tasks (Metrics & Logs): get_tasks_workspace_summary, get_task_time_tracking, get_task_description, get_task_count, get_task_usage

  • Labels & Tags: get_labels, get_note_tags

  • Comments & Activity Stream: get_activity_stream, get_comment_threads, fusebase_poll_mentions, fusebase_post_comment, fusebase_reply_comment, fusebase_resolve_thread

  • Files & Storage: get_file_count

  • Organization 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_usage

  • Workspaces & Subscription: get_workspace_premium_status, get_active_import_status, get_workspace_detail, get_workspace_emails, get_workspace_info

  • Navigation & 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_notes

  • Databases & 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_alias

  • Views: update_view, set_view_representation, create_view, delete_view, duplicate_view, set_view_grouping

  • Columns: add_database_column, delete_database_column, rename_database_column, reorder_database_columns, set_column_width, add_relation_column, add_lookup_column

  • Cells & Rows: update_database_cell, get_database_rows, get_database_schema, reorder_database_rows

  • Direct 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_call

  • CLI updates: fusebase_cli_update previews the official update by default. Set dryRun: false to apply; includeProduct: true also refreshes managed product assets, MCP configuration and dependencies. Git checkpoints are disabled. fusebase_cli_app_update supports access principals, additive Gate permission sync, and named environments; build settings belong in fusebase.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_rows

  • Gate 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_migrations

  • Billing & User Preferences: get_billing_info, get_user_preferences, set_sidebar_collapsed

  • Import/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) or FUSEBASE_SECRET_KEY

  • 1Password — keep tokens and FUSEBASE_SECRET_KEY in 1Password, put only op:// references in .env, and start the server with op run --env-file=.env -- node dist/index.js. Vault items or a 1Password Environment both work. See docs/1PASSWORD.md

  • Auto-refresh — expired sessions are transparently refreshed via Playwright

  • .env is gitignored — credentials never enter version control

  • Cookie via env var — optionally pass FUSEBASE_COOKIE in 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 suites

Command

What it checks

npm test

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

npm run test:audit

Every tool has a description and described parameters, no duplicate tools, every tool documented in README.md

npm run test:token

Gate/Dashboards token identity, permission catalog, token list, isolated stores

npm run test:mcp-e2e

MCP resources, prompts, tier switching and a full page lifecycle over stdio

npm run test:regression

Every block type and inline format written over the Y.js WebSocket and read back

npm run test:database

Database, column, row, view, relation, CSV and cloning lifecycle

npm run test:automation

Disposable flow configuration, publication, two distinct executions with verified outputs, and cleanup

npm run test:account -- --preferences --refresh-auth

Explicit account-wide preference restore and persisted browser-auth refresh checks

npm run test:data-validation

Live calls across the tool catalog with data-shape and round-trip assertions

npm run test:parity

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

  1. 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)

  2. npm run test:live for any change that touches API calls, content writing or auth

  3. npm run deploy:status if you maintain the status dashboard

🤝 Contributing

  1. Fork the repo

  2. Create a feature branch

  3. Run npm run build to verify TypeScript compiles

  4. Submit 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      47
      13 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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