fusebase-mcp: Instructions file for Codex

FuseBase MCP — AI Agent Instructions & Playbook

Target Audience: Autonomous AI coding agents (Claude Code, OpenAI Codex, Cursor Agent, Antigravity, Devin, Aider, OpenCode, Windsurf). Purpose: Connect to, interact with, and manipulate FuseBase workspaces efficiently with zero token waste and zero context clutter.

---

1. Context Protection & Tool Tiers (CRITICAL)

FuseBase MCP provides 177 production tools. Registering all 177 tools at once can consume 15,000–20,000 tokens of your context window just in schema definitions.

To protect your context window, this server implements a Two-Tier System:

1. Core Tier (34 Tools — Active by Default):
   • Covers complete everyday CRUD for Pages/Notes, Folders, Comments, Mentions, Tasks, Attachments, Members, Profiles, and Guides.
   • Default behavior: Keep the server in Core Tier for document editing, research, and note-taking.
2. Extended Tier (143 Tools — Activated On Demand):
   • Unlocks Relational Databases (views, rows, columns, lookups, relations), Client Portals, ActivePieces Automations, Gate PostgreSQL isolated stores, API token creation, and Swarm boards.
   • How to activate: When your task requires databases, portals, or automations, call:

     {
       "tool": "set_tool_tier",
       "arguments": { "tier": "all" }
     }
     

   • Or launch with env: Set FUSEBASE_TOOLS=all in your agent MCP environment configuration if your entire session is dedicated to database/portal development.

---

2. Authentication Modes (Zero-Browser Recommended)

FuseBase MCP supports three authentication methods:

Mode 1: Pure Token Mode (Recommended for Autonomous Agents)

Autonomous agents cannot solve interactive browser captchas. Token mode connects directly to official FuseBase Gate & Dashboards remote MCP endpoints with zero browser dependency. It covers only part of the tool set (pages and folders: list, read, create, append; database listing; isolated SQL stores; Gate tokens). Tasks, comments, tags, members, page rename/move/delete, automations and most database tools need Mode 2 or 3; see docs/TOKEN-COVERAGE.md.

# In your agent config or .env:
FUSEBASE_GATE_TOKEN=your_gate_mcp_token
FUSEBASE_DASHBOARDS_TOKEN=your_dashboards_mcp_token
# or unified platform token:
# FUSEBASE_TOKEN=your_token

Zero Configuration: Upstream whoami automatically discovers your tenant orgId, domain host, and default workspace ID. No cookies or local browser binaries needed.