Ideafy's MCP server

Ideafy ships its own MCP (Model Context Protocol) server. That server is the bridge between your AI agent and the Ideafy board. When an agent calls save_plan or list_cards, it's talking to this server — and the server is writing directly to your local SQLite database and, in the Team edition, syncing to Supabase for pool-linked projects.

What's in the server

The server file is mcp-server/index.ts and exports 15 tools (11 in the Public edition, plus 4 pool tools in the Team edition), grouped into five families:

• Local (CRUD) — get_card, create_card, update_card, move_card, list_cards, get_project_by_folder
• Workflow — save_plan, save_tests, save_opinion
• Branch — ensure_branch (remediation for the PreToolUse branch-enforcement hook; see hooks)
• Session — bind_session_to_card (associates a Claude Code session with a specific card)
• Pool (Team edition only) — pool_list, pool_push, pool_pull, pool_claim

See MCP tools reference for each tool's signature and side effects.

How it's packaged

Two distribution paths depending on the agent you use:

• Claude Code — the MCP server ships inside the Claude Code plugin as a compiled mcp/index.js. Claude Code spawns it via node ${CLAUDE_PLUGIN_ROOT}/mcp/index.js — ${CLAUDE_PLUGIN_ROOT} expands to the install cache path at runtime, so the config is portable across machines.
• Gemini / Codex — the server runs from source via npx tsx mcp-server/index.ts. Ideafy writes the invocation into the platform's config file when you enable the project toggle.

In every case, your agent spawns the server on demand, the server reads SQLite, responds, the agent continues. You don't see or manage the process.

Configuration

Two shapes, depending on the platform:

Claude Code (via plugin) — no manual entry. The plugin's .mcp.json declares:

{
  "mcpServers": {
    "ideafy": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/index.js"]
    }
  }
}

Enable the toggle under Settings → General → Claude Code plugin (global) or Edit Project → Claude Code plugin (project scope) and Claude Code picks it up on next restart.

Gemini / Codex — Ideafy writes an entry into the platform's config file (~/.gemini/settings.json or ~/.codex/config.toml). The command points at the bundled TypeScript source and runs it through tsx:

{
  "mcpServers": {
    "ideafy": {
      "command": "npx",
      "args": ["tsx", "<path-to-ideafy>/mcp-server/index.ts"]
    }
  }
}

For the normal case, enable the Ideafy MCP & Skills toggle in project settings (see MCP & Skills installation) and don't think about it.

Database path

The server resolves the SQLite DB path cross-platform, so every consumer (the Ideafy app, the Claude Code plugin MCP, Gemini MCP, Codex MCP) reads and writes the same kanban.db. A card created in the Ideafy UI is visible to mcp__ideafy__list_cards immediately, regardless of which agent asks.

Override with the IDEAFY_USER_DATA environment variable — useful in dev to point at a scratch DB. Ideafy's own packaged Electron bundle sets this explicitly to app.getPath("userData"), which matches the OS defaults above.

Environment variables

The server reads a small set of env vars:

Everything else — database path, Supabase credentials (for cloud pool sync), auth tokens — is read from the Ideafy SQLite database's settings table. The server has access to the same local state the app does.

How pool operations work

Local CRUD tools write SQLite directly. Pool tools (cloud only) go through the Ideafy API instead — the server calls localhost:${PORT}/api/team/pool* with the stored Supabase auth token. This matters because:

• Pool writes need authentication the MCP server can't perform itself
• The server uses the API to get the benefits of the API's validation (subscription check, team membership check, seat limits)
• A fire-and-forget /api/internal/sync-card call fires on every local mutation, so pool-linked cards stay in sync without extra tool calls

If you're on the Public edition, the pool tools simply aren't available — they aren't bundled in that build.

Pointing your own project at the server

For Claude Code, the plugin toggle handles everything — global or project scope, one click.

For Gemini / Codex, use the project settings modal's Ideafy MCP & Skills toggle, or do it by hand:

1. Locate the bundled mcp-server/index.ts (path shown in the project settings modal)
2. Add an mcpServers.ideafy entry to the platform's config file (~/.gemini/settings.json or ~/.codex/config.toml)
3. Restart your agent CLI so it picks up the new config
4. Test with a simple call — ask the agent to list cards in the project

Troubleshooting quick refs

• Agent doesn't see the tools: agent CLI not restarted after config change, or config file in the wrong place. Run claude mcp list (or platform equivalent).
• Tools return "project not found": the server resolves project by folder path. Run the agent from inside the project directory.
• Pool tools missing: Public edition, or Supabase not configured, or user not signed in.

Full troubleshooting: Troubleshooting.

Prev: Choose an AI agent Next: Claude Code plugin Up: User guide index