toggle-brain MCP Server

A Model Context Protocol server that exposes the Toggle Brain knowledge base, prompt templates, and executable scripts to any MCP-compatible AI assistant — Claude Code, Cursor, Windsurf, and more.

Content lives in the toggle-brain repository and is automatically synced here on every push. You never need a GitHub token, API keys, or manual updates at runtime — just clone, build, and connect.

---

What it exposes

MCP primitive	Source in toggle-brain	Example
Resources	brain/, cockpit/, clients/, templates/, archive/	kb://brain--services--copywriting
Prompts	generators/, playbooks/	generators--email-sequence
Tools	Any .ts or .py file in the repo	brain_scripts_audit

---

Prerequisites

• Node.js 20 LTS or later

That's it. No tokens, no API keys, no external services.

---

Setup

1. Clone the repo

git clone https://github.com/toggle-workspace/toggle-mcp.git
cd toggle-mcp

2. Install dependencies and build

npm install
npm run build

3. Verify it works

node dist/index.js
# Loaded: 153 resources, 15 prompts, 1 tools

---

Connecting to Claude Code

From inside the cloned toggle-mcp directory, run:

claude mcp add toggle-brain node "$(pwd)/dist/index.js"

Then run /mcp inside a Claude Code session to confirm it is connected:

/mcp
# toggle-brain — Connected

---

Connecting to Cursor

Add to ~/.cursor/mcp.json (or via Cursor Settings → MCP):

{
  "mcpServers": {
    "toggle-brain": {
      "command": "node",
      "args": ["/path/to/toggle-mcp/dist/index.js"]
    }
  }
}

Replace /path/to/toggle-mcp with the actual path where you cloned the repo.

---

Connecting to Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "toggle-brain": {
      "command": "node",
      "args": ["/path/to/toggle-mcp/dist/index.js"]
    }
  }
}

Replace /path/to/toggle-mcp with the actual path where you cloned the repo.

---

Remote / HTTP mode

Set TRANSPORT=http to run as an SSE server on a fixed port:

TRANSPORT=http PORT=3000 node dist/index.js

Point any MCP client at http://localhost:3000/sse.

---

Usage

Once connected, the AI assistant can:

• Browse knowledge — ask it to read resources like "summarise the Toggle Brain positioning docs" or reference kb://brain--services--copywriting directly
• Run prompt templates — ask it to use a prompt like generators--email-sequence with your variables filled in
• Execute tools — any .ts or .py scripts from toggle-brain are callable as tools

In Claude Code, confirm what is loaded at any time:

/mcp

---

For maintainers

How the sync works

Content in this repo is kept up to date by a two-step GitHub Actions pipeline:

1. toggle-brain runs .github/workflows/notify-mcp.yml on every push to main. This workflow dispatches a repository_dispatch event of type toggle-brain-updated to the toggle-mcp repository.
2. toggle-mcp has .github/workflows/sync-brain.yml which listens for that event, checks out toggle-brain, copies its contents into this repo, and commits and pushes the result.

The MCP server reads from the local content/ directory at runtime — no network calls, no tokens required for end users.

Required secret

The toggle-brain notify workflow needs a GitHub PAT stored as a repository secret named GH_PAT. This token must have:

• repo scope (to dispatch events to toggle-mcp)
• workflow scope (to trigger Actions workflows)

Add it at: toggle-brain repo → Settings → Secrets and variables → Actions → New repository secret

Adding the notify workflow to toggle-brain

See TOGGLE_BRAIN_SETUP.md for the step-by-step guide. In short, create .github/workflows/notify-mcp.yml in the toggle-brain repository with the content from toggle-brain-notify-workflow.yml in this repo.

Once this is in place, every push to toggle-brain/main will automatically update the content in this repo within seconds.

---

Troubleshooting

Symptom	Fix
toggle-brain not in /mcp list	Re-run claude mcp add ... and restart the session
Resources show as empty or missing	Run git pull to get the latest synced content, then rebuild
Build fails with type errors	Ensure Node.js 20 or later is installed (node --version)
Sync Action fails in toggle-brain	Check that the GH_PAT secret is set with repo and workflow scopes
Sync Action fails in toggle-mcp	Check that sync-brain.yml is present and the dispatch event type matches brain-updated
HTTP mode not reachable	Confirm TRANSPORT=http and PORT are set, and that the port is not blocked by a firewall