MCP Server & CLI

GoalPath speaks MCP (Model Context Protocol), the open standard for connecting AI assistants to external tools. Once connected, your assistant can see what's assigned, update item status, check off subtasks, post progress notes, and ask questions about your project's health. No tab-switching or copy-pasting item IDs required.

There are two ways to connect: a hosted server (recommended for most setups) and a local CLI. Both expose the same 38 tools. The difference is how they connect and how they resolve which project you're working on.

Hosted MCP server (recommended)

The fastest way to connect. No install, no API key, no config files.

Endpoint:

https://goalpath.app/api/mcp

This works with any AI tool that supports remote MCP servers, including Claude Desktop, Claude Code, Claude.ai, Claude mobile, Cursor, VS Code Copilot, and Windsurf.

Because it's built on the open MCP spec, it will also work with future AI tools from other providers as they add remote MCP support.

Setup: Claude Desktop

Go to Settings > Connectors > Add URL
Paste https://goalpath.app/api/mcp
Claude opens a browser window. Log in to GoalPath and click Allow.

That's it. Your assistant now has access to your GoalPath projects. The OAuth token refreshes automatically, so you only authenticate once.

Setup: Claude Code

bash

claude mcp add goalpath-remote --url https://goalpath.app/api/mcp

Claude Code will prompt you to authenticate via browser the first time.

Setup: Cursor / VS Code / Windsurf

Add this to your MCP configuration (check your tool's docs for the config file location):

json

{
  "mcpServers": {
    "goalpath": {
      "url": "https://goalpath.app/api/mcp"
    }
  }
}

Your tool will handle the OAuth flow when it first connects.

Setup: API key (any client)

If your MCP client doesn't support OAuth, generate an API key at Profile > API Keys and pass it as a Bearer token:

Authorization: Bearer gp_xxxxx

How the hosted server picks your project

Without a local .goalpath file, the hosted server needs another way to know which project you're working on. It uses this priority:

Explicit projectId in the tool call (your assistant can pass this directly)
Active project set via the set_active_project tool (persists across requests)
Most recently used project from your account (automatic fallback)

If you work on a single project, you'll never think about this. If you work on multiple, your assistant will call list_projects and set_active_project when it's unclear which one you mean.

Local CLI

The CLI gives you two things the hosted server can't: automatic project resolution from your repo and terminal commands for quick lookups without an AI assistant.

Install it if you want your AI assistant to automatically know which project a codebase belongs to, or if you prefer terminal access to GoalPath.

Install

bash

npm install -g @goalpath/cli

Authenticate

bash

goalpath login

Paste your API key when prompted. Generate one at Profile > API Keys in GoalPath, or go directly to goalpath.app/profile/api-keys.

For CI or scripted setups: `goalpath login --api-key gp_xxxxx`

Link your repository

bash

goalpath project link

This creates a .goalpath file in your repo root. Commit it. When your teammates clone the repo, their CLI and AI assistant will automatically know which GoalPath project this codebase belongs to. No set_active_project call needed.

If you work on multiple projects, override the linked project with the GOALPATH_PROJECT_ID environment variable.

Connect your AI assistant

bash

goalpath mcp init

Auto-detects Claude Code, Claude Desktop, Cursor, and VS Code. Adds GoalPath to their MCP configuration without overwriting anything.

Target a specific tool:

bash

goalpath mcp init claude-desktop
goalpath mcp init cursor
goalpath mcp init vscode

Manual config: add this to your tool's MCP config file (`.mcp.json` for Claude Code, `claude_desktop_config.json` for Claude Desktop):

json

{
  "mcpServers": {
    "goalpath": {
      "command": "goalpath",
      "args": ["mcp", "serve"]
    }
  }
}

CLI commands

For quick terminal access without an AI assistant:

bash

goalpath items --mine              # Your assigned items
goalpath items --status Started    # Filter by status
goalpath items --milestone "v2.1"  # Filter by milestone
goalpath status                    # Project summary
goalpath project list              # All your projects

Which should I use?

Use the hosted server if you want the simplest setup, connect from mobile or browser, or use a tool that supports remote MCP.

Use the CLI if you want automatic project resolution from .goalpath files committed to your repos, or if your AI tool only supports stdio-based MCP servers.

Use both if you want the CLI's repo-aware project resolution in your coding tool and the hosted server for Claude Desktop, mobile, or browser access. They don't conflict.

	Hosted server	Local CLI
Install required	No	Yes (`npm install -g @goalpath/cli`)
Setup	Paste URL, log in via browser	Install, authenticate, link, configure
Project resolution	Manual (`set_active_project`) or automatic fallback	Automatic from `.goalpath` file in repo
Works on mobile / Claude.ai	Yes	No
Works with non-Claude AI tools	Yes (any MCP client with remote support)	Yes (any MCP client with stdio support)
Terminal commands	No	Yes (`goalpath items`, `goalpath status`)
Team project sharing	Via `set_active_project` per user	Via `.goalpath` file committed to repo

What your assistant can do

Both connection methods expose the same 38 tools across work management, planning, and project insights.

The everyday workflow

What you ask	What happens
"What's assigned to me?"	Calls `list_my_items` to show your items with status and priority
"Show me the details for this item"	Calls `get_item` to return the full description, subtasks, and comments
"Start working on the login bug"	Calls `set_item_status` to mark it as Started
"Check off the first subtask"	Calls `check_task`. Stakeholders see the checkbox update in real time
"Post a comment with the PR link"	Calls `add_comment` to add a note visible to the whole team
"Mark it as finished"	Calls `set_item_status` to move it to Finished
"Move this to the icebox"	Calls `move_to_icebox` to deprioritize the item

Milestones and planning

Your assistant can list milestones, read PRDs from milestone descriptions, create new items, move items between milestones, and check forecasts. Useful for planning sessions where you want to break a milestone into items without leaving your editor.

Highlights and blockers

When your assistant hits a blocker or has a question about requirements, it can flag items directly:

set_item_highlight("Blocked", "Waiting for API credentials"): flags the item and explains why
set_item_highlight("Question", "Should this support mobile?"): surfaces the question to the team

These show up immediately in GoalPath for stakeholders and teammates to see.

Project insights (Teams & Insights addon)

With the Teams & Insights addon, your assistant can answer questions about your project's health using the same data GoalPath's Insights dashboard shows:

What you ask	What happens
"Are we on track?"	Calls `list_insights` to get GoalPath's precomputed analysis across 17 health dimensions
"What's our velocity trend?"	Calls `get_velocity_history` for week-by-week throughput data
"How much unplanned work are we taking on?"	Calls `get_unplanned_work_trend` for the planned vs unplanned ratio
"Where is work getting stuck?"	Calls `get_flow_metrics` for flow time, efficiency, and distribution
"How many items are blocked?"	Calls `get_highlight_count` for blocked, question, and discussion counts
"Is our inbox clean?"	Calls `get_triage_health` for inbox triage status

GoalPath precomputes answers to 17 standard insight questions weekly, including signals, suggestions, and confidence levels. When your assistant uses list_insights, it gets GoalPath's own analysis rather than trying to interpret raw metrics, so answers are aligned with what the Insights dashboard shows.

Insight tools require the Teams & Insights addon ($49/mo). Without it, these tools return a message directing you to upgrade at Settings > Billing.

How autonomous agents use it

GoalPath offers a full set of AI skills that turn your assistant into an autonomous collaborator, from discovering ideas to shipping PRs:

Picks up an item: reads the description and subtasks
Sets status to Started: the team sees work has begun
Does the coding work: implements the feature or fix
Checks off subtasks: progress is visible in real time, not batched at the end
Posts a comment: links the PR or summarizes what changed
Marks it Finished: signals that the work is ready for review

Stakeholders see progress as it happens. No one needs to write a status update or schedule a sync meeting.

Configuration reference

Where config lives (CLI only)

File	Purpose	Scope
`~/.goalpath/config.json`	API key, default project	Per user
`.goalpath`	Linked project ID	Per repo (commit this)

Project resolution (CLI)

When the CLI needs to know which project to use, it checks in this order:

GOALPATH_PROJECT_ID environment variable (highest priority)
.goalpath file in the current directory or any parent
defaultProjectId from ~/.goalpath/config.json

Environment variables (CLI)

Variable	Purpose
`GOALPATH_API_KEY`	API key (overrides config file)
`GOALPATH_URL`	Base URL (default: goalpath.app)
`GOALPATH_PROJECT_ID`	Project ID (overrides .goalpath file)