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 14 tools, grouped into three families:

• Local (CRUD) — get_card, create_card, update_card, move_card, list_cards, get_project_by_folder
• Workflow — save_plan, save_tests, save_opinion
• 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

The server runs via npx tsx — just-in-time TypeScript transpilation. No build step, no compiled binary; your agent spawns it as a subprocess on demand. In practice, the agent spawns the server, the server reads SQLite, the server responds, the agent goes on with its reply. You don't see or manage the process.

Configuration

The entry Ideafy writes into your project's .claude/settings.json (or equivalent):

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

The path points at the bundled server shipped with the Ideafy app. You can override it by running your own copy of the server — useful if you're hacking on the tools. For the normal case, use the in-app Install Ideafy MCP button in project settings and don't think about it.

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

If you already opened the project's settings modal and clicked Install Ideafy, you're done. If you want to do it by hand:

1. Locate the bundled mcp-server/index.ts (it ships with the app; its path is shown in the project settings modal)
2. Add an mcpServers.ideafy entry to .claude/settings.json with the JSON above
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

The same approach works for Gemini CLI and Codex CLI, just with different config files.

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: Bundled Claude Code skills Up: User guide index