Model Context Protocol (MCP)

Connect external AI assistants—including Claude Desktop, Cursor, Antigravity, Windsurf, and VS Code—directly to your local Noust workspaces in real time.

The official @noust-app/mcp server provides secure, local bidirectional communication between AI models and your notes, free-text Nexus documents, and canvas topology.

---

What Can AI Do in Your Workspace?

Instead of copying and pasting notes into chatbots, MCP gives your AI assistant direct, autonomous access to understand and interact with your canvas:

• 🔍 Intelligent Search & Consultation: Ask your AI assistant to search across notes, Nexus pages, and objectives. The model retrieves full contents without truncation while ignoring HTML/CSS tags.

  "Search my Noust workspace for our deployment checklist and summarize the remaining tasks."

• ✍️ Real-Time Canvas Creation, Editing & Deletion: The AI assistant can create new note cards, update existing text, or delete obsolete notes live on your screen while you watch.

  "Create a new note on my canvas with the 3 main takeaways from this discussion."

• 🎯 Objectives & Milestones Management: Track and manage project goals autonomously. AI models can create new objectives, update status and deadlines, mark tasks as completed, append progress updates, or remove items.

  "Add a high-priority objective to deploy staging before Friday and mark the previous database migration goal as completed."

• 📄 Full Nexus Documents Control: Organize long-form knowledge effortlessly. Your assistant can create new global Nexus documents, append markdown sections, rewrite contents, or delete documents.

  "Create a new Nexus document titled 'API Architecture' detailing the endpoints discussed."

• 🏷️ Reusable Flags & Color Harmony: Inspect and create custom flags for your canvas domains. Your assistant can check existing flag colors (list_flags), craft distinctive shades on request (e.g. choosing a unique tone of orange), or generate balanced palettes automatically.

  "List all current flags in this domain and create a new 'Code Review' flag with a distinct shade of orange."

• 🧭 Interactive Visual Navigation: Ask the AI to locate anything on your board or view documents. Noust automatically pans, zooms, and highlights target notes on the canvas or opens focused Nexus documents.

  "Show me where the marketing sprint objectives are located on my canvas."

• 🖼️ Multimodal Vision for Embedded Images: Vision-capable models (Claude 3.5 Sonnet, GPT-4o, Gemini) can inspect embedded images, mockups, and diagrams attached to your notes.
• 📦 Direct Context via MCP Resources: Rather than issuing tool queries, AI assistants and IDEs can mount notes, documents, and workspace metadata directly into their context window via standard MCP resource URIs (noust://).

  "Inspect noust://workspace/active to understand the domain topology before making recommendations."

• 🗂️ Multi-Workspace & Cross-Tab Routing: Work across multiple open workspaces concurrently. The AI assistant can inspect active tabs, target a specific workspace by name using the workspace parameter, or seamlessly interact with the local directory anchor.

  "List my active workspaces and add a new release note to the 'Mobile App' workspace."

---

Dual-Mode Architecture

@noust-app/mcp is designed to be resilient whether Noust is currently open or closed:

1. Offline / File-Only Mode: When Noust is closed, the MCP server reads directly from your linked local .noust file on disk. Models can perform deep text searches, retrieve notes by ID or human reference (e.g. 1A1), and inspect images completely offline.
2. Live Bridge Mode (Zero-Trust): When Noust is open in a Chromium browser with local folder sync and MCP enabled (Agent panel in the Menu Shell), an ephemeral local WebSocket bridge (127.0.0.1:8421) connects to execute live canvas mutations, create notes, and navigate your board on demand.

Encrypted Workspaces

If the .noust file is encrypted with a user password, the MCP server will only operate with Noust open and active in the browser. This ensures that AI agents cannot read the content of .noust directly from disk and are strictly required to use the official tools via MCP Server.

Multi-Workspace & Cross-Tab Routing

Noust supports opening different workspaces simultaneously across multiple browser tabs, each linked to its own local folder. @noust-app/mcp handles multi-workspace environments cleanly and predictably:

• Local Workspace Anchor: When the MCP server is launched with --workspace <folder>, it detects the local .noust file in that directory. If a browser tab is syncing that workspace, all operations automatically target that tab by default.
• Single Active Tab: If only one workspace tab is active in your browser, operations automatically route to it without requiring an explicit workspace parameter.
• Cross-Tab Disambiguation: When multiple workspaces are active across browser tabs and the client is running outside a specific workspace directory (or targeting another tab), all tools accept an optional workspace parameter. If ambiguous, the server lists the active workspace names and prompts the assistant to specify which workspace to inspect or edit.
• Workspace Status Inspection: The get_workspace_status tool reports all active browser sessions, connected workspaces, and the current default target.

---

Standard MCP Resources

Beyond actionable tools, @noust-app/mcp implements the official Model Context Protocol Resources specification (resources/list and resources/read). Compatible AI clients—such as Claude Desktop, Cursor, and Antigravity—can inspect workspace state or attach specific notes and documents directly into the prompt context without executing tool calls:

Resource URI	Type	Format	Description
noust://workspace/active	Static	JSON (application/json)	Complete overview of the active workspace, including workspace ID, workspace name, domains, note counts, Nexus document counts, and live bridge connection state.
noust://notes/{noteId}	Dynamic Template	Markdown (text/markdown)	Complete content of a canvas note formatted as clean Markdown (with title header, domain, canvas reference 1A1, and body). Automatically populated via resources/list.
noust://documents/{docId}	Dynamic Template	Markdown (text/markdown)	Complete content of a Nexus free-text markdown document (with title and body). Automatically populated via resources/list.
noust://objectives/active	Static	JSON (application/json)	Real-time list of all active goals, milestones, categories, and assigned color-coded flags in the workspace.

Resource Auto-Discovery & Dual-Mode

• Context Auto-Complete in IDEs: Clients supporting resources/list automatically display all notes and Nexus documents in their resource pickers (e.g. @ context references in Cursor or Claude Desktop's resource browser).
• Dual-Mode Continuity: If Noust is running in your browser with bridge enabled, resources reflect live, in-memory state. When Noust is closed, resources load directly from the local .noust file on disk.

---

Quick Setup & Configuration

You do not need to install anything globally. MCP clients execute the server on demand via npx.

Prerequisites

1. Node.js >= 18.0.0 installed on your machine.
2. A Noust workspace linked to a local folder via Automatic Local Sync.
3. Enable MCP Bridge in Noust under the Agent panel in the Menu Shell.

1. Claude Desktop

Add noust to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "noust": {
      "command": "npx",
      "args": [
        "-y",
        "@noust-app/mcp",
        "--workspace",
        "/absolute/path/to/your/noust-workspace-folder"
      ]
    }
  }
}

Windows Path Formatting

In JSON configuration files on Windows, paths must use escaped backslashes (e.g., "C:\\Users\\YourName\\Documents\\Noust") or standard forward slashes (e.g., "C:/Users/YourName/Documents/Noust") to avoid JSON syntax errors.

2. Cursor IDE

Add noust to your project's .cursor/mcp.json or in Settings > Features > MCP Servers:

{
  "mcpServers": {
    "noust": {
      "command": "npx",
      "args": [
        "-y",
        "@noust-app/mcp",
        "--workspace",
        "/absolute/path/to/your/noust-workspace-folder"
      ]
    }
  }
}

3. Antigravity IDE

Add noust to your workspace mcp_config.json:

{
  "mcpServers": {
    "noust": {
      "command": "npx",
      "args": [
        "-y",
        "@noust-app/mcp",
        "--workspace",
        "/absolute/path/to/your/noust-workspace-folder"
      ]
    }
  }
}

---

Security & Privacy (Zero-Knowledge)

Cloud AI Models & Data Privacy

While Noust and @noust-app/mcp operate 100% locally on your machine (127.0.0.1) and never transmit your notes or data to Noust servers, any information read or retrieved by MCP tools (search_workspace, get_note, get_document, get_objective, etc.) becomes prompt context for your connected AI assistant.

If your assistant connects to third-party cloud models (such as Claude/Anthropic, ChatGPT/OpenAI, or Gemini/Google), the retrieved workspace contents are sent over the internet to that model provider's servers according to their respective privacy policies and retention terms.

If you require absolute data sovereignty or work with strictly confidential data, configure your MCP client to use local, self-hosted LLMs (e.g., via Ollama, LM Studio, or local open-source models).

@noust-app/mcp follows strict local-first security principles:

• 100% Local Loopback: All traffic is strictly confined to 127.0.0.1. No notes, tokens, or metadata are ever transmitted to any external server.
• Ephemeral Shared Secret Token: Each live session generates a random 256-bit token (.noust-bridge.token) restricted to OS file permissions 0600. Only the local browser tab holding granted filesystem access can authenticate.
• Path Confinement: The server uses canonical realpaths and strictly refuses to access files outside the authorized workspace directory or without the .noust extension.
• Input Sanitization: All content generated by external AI agents is automatically sanitized via DOMPurify before rendering to prevent malicious HTML or script injections.
• CSWSH & DNS Rebinding Immunity: The bridge rejects unauthorized Host headers and arbitrary browser origins.
• Encrypted Workspaces: If the .noust workspace file is encrypted with a user password, the MCP server will only operate with Noust open and active in the browser. This ensures that AI agents cannot read the content of .noust directly from disk and are strictly required to use the official tools via MCP Server.

---

Technical Documentation & Source Code

For developers, CLI options (-d / -r), and complete tool schemas, visit the official open-source repository:

🔗 GitHub: noust-app/mcp