🤖 MCP (Model Context Protocol)

CanGoal ships with a built-in MCP (Model Context Protocol) Server, so AI assistants like Claude Desktop, Cursor, and ChatGPT Desktop can read and manage your goals, tasks, timing sessions, notes, and statistics directly through a secure local connection.

• Protocol: MCP 2025-06-18 + JSON-RPC 2.0
• Transport: stdio only (stdin/stdout) — no HTTP or WebSocket server
• Tools: 22 (Goal 6 / Task 6 / Timing 3 / Note 5 / Stats 2)
• Platform: macOS only (iOS processes cannot be spawned by desktop clients)

MCP runs as a separate helper executable bundled inside CanGoal, so it never interferes with the main app — your GUI and the AI assistant can run at the same time.

What MCP Lets Your AI Do

Once connected, your AI assistant can:

• Read your data — list goals, tasks, timing records, notes, and statistics.
• Create and edit — add goals and tasks, complete tasks, start/stop focus timers, and add notes.
• Track progress — query statistics and per-goal quantification progress.

Everything the AI does goes through the exact same business logic as the CanGoal app, so streaks, widgets, notifications, and CloudKit sync all behave identically.

Connecting Your AI Client

The MCP helper lives inside the installed app at:

/Applications/CanGoal.app/Contents/Helpers/CanGoalMCP.app/Contents/MacOS/CanGoalMCP

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cangoal": {
      "command": "/Applications/CanGoal.app/Contents/Helpers/CanGoalMCP.app/Contents/MacOS/CanGoalMCP",
      "args": []
    }
  }
}

Restart Claude Desktop. You should see the cangoal server's 22 tools appear in the tools menu.

Cursor

Go to Settings → MCP Servers → Add new MCP Server:

• Type: command
• Name: cangoal
• Command: /Applications/CanGoal.app/Contents/Helpers/CanGoalMCP.app/Contents/MacOS/CanGoalMCP

ChatGPT Desktop

Go to Settings → Connectors → Add new connector and use the same JSON as Claude Desktop.

Available Tools (22)

Goal (6)

• list_goals — list all goals, optionally filter by status / active
• get_goal — get goal details (progress, stats summary)
• create_goal — create a goal (name, type, color, deadline, quant_target)
• update_goal — update goal fields
• delete_goal — soft-delete a goal
• list_goal_templates — list available goal templates

Task (6)

• list_tasks — list tasks, filter by goal / date / status
• get_task — get task details (checklist, streak)
• create_task — create a task under a goal
• update_task — update task fields
• complete_task — mark a task complete (triggers streak / widget / notification, same as GUI)
• delete_task — delete a task

Timing (3)

• start_timing — start a focus session for a task (stopwatch or pomodoro)
• stop_timing — stop the current session, writing a TimingRecord + GoalEvent
• list_timing_records — query timing history

Note (5)

• list_notes — query notes by goal / task / date
• get_note — get a note's full content
• add_note — add a text note to a goal or task
• update_note — edit a note
• delete_note — delete a note

Stats (2)

• get_statistics — global statistics (today's completed count, streak, total timing, goal overview)
• get_goal_progress — quantification progress + per-task contributions for a goal

Privacy & Security

• MCP runs entirely locally via stdio — your data never goes through any extra server.
• The helper reads and writes the same Core Data store as the CanGoal app (via the App Group container), protected by the App Sandbox.
• No personal data is collected or transmitted by the MCP connection itself; it only accesses what's already in your CanGoal database.
• CloudKit sync keeps the data consistent between the MCP helper and the GUI, exactly as it does across your devices.

Troubleshooting

• AI client can't see the tools — Command path points to the old main binary with --mcp. Fix: use the helper path under Contents/Helpers/CanGoalMCP.app/..., and remove the --mcp argument.
• Tool returns isError: true — Business error (resource not found / state conflict / bad params). Fix: read the message in content[0].text.
• Tool returns JSON-RPC error -32602 — Wrong tool name or schema mismatch. Fix: run tools/list to re-check the schema.
• Helper reads empty data — Core Data store mismatch. Fix: confirm the app is installed and has data; the helper shares the same store.

Notes

• MCP is macOS only — iOS apps cannot be spawned by desktop AI clients.
• Only stdio transport is supported (no HTTP / WebSocket / SSE).
• A single helper process serves one client session at a time.
• The resources/* and prompts/* MCP methods are not supported; only tools/*.