Pheidi MCP Server

Pheidi runs a Model Context Protocol (MCP) server so an AI assistant — Claude Desktop, claude.ai, VS Code, or any MCP-capable client — can act on your training plan for you. Ask "what's my run today?" or "log my 6-miler, felt easy" and the assistant reads your real plan and records the workout against your account.

Endpoint

https://app.pheidi.training/mcp

Transport — Streamable HTTP.
Auth — OAuth 2.1 with PKCE (MCP 2025-06-18). You sign in once in your browser; the assistant never sees a password or API key.
Discovery — clients auto-discover the OAuth endpoints from /.well-known/oauth-protected-resource (RFC 9728) and /.well-known/oauth-authorization-server (RFC 8414). Dynamic Client Registration (RFC 7591) is supported, so most clients connect with nothing but the URL above.

What an assistant can do

The server exposes eight tools. Three read your plan; five make changes — always at your explicit request.

Read

get_active_plan — summary of your currently active plan: race goal, status, total weeks.
get_today_workout — today's scheduled workout in your local time zone.
list_upcoming_workouts — the next N days of workouts (1–28, default 7).

Write

record_workout — mark a workout completed or skipped, with optional distance, duration, effort, and how it felt.
report_injury — log a niggle or injury (body part + 1–10 severity) so the plan can adapt.
add_vacation — block out a travel/rest window so the plan reduces or removes those workouts.
update_profile — update VDOT, current weekly mileage, units, or running experience.
submit_feedback — file a bug or feature request straight into the same review queue as in-app feedback.

The server also publishes three read-only context resources an assistant can pull without invoking a tool: pheidi://plans/active, pheidi://workouts/today, and pheidi://workouts/week.

Connecting a client

Add Pheidi as a remote MCP server using the endpoint URL. For clients that support remote MCP servers natively:

{
  "mcpServers": {
    "pheidi": {
      "url": "https://app.pheidi.training/mcp"
    }
  }
}

On first use the client opens a browser window to sign in to Pheidi (one-time code by email) and authorize access. After that it holds a refreshable token — you won't be asked again until it expires. Clients that don't yet speak remote MCP directly can bridge over stdio:

npx mcp-remote https://app.pheidi.training/mcp

To explore the server by hand, the MCP Inspector (npx @modelcontextprotocol/inspector) walks the full OAuth flow and lets you invoke each tool.

MCP server vs. the Plan API

Pheidi exposes two integration surfaces, for two jobs:

Public Plan API — read-only JSON for a single plan by its publicId. No auth, anyone with the ID can read it. Best for sharing a plan with a tool or agent that only needs to read.
MCP server — authenticated, scoped to your account, and able to write (log workouts, report injuries, edit your profile). Best for a personal assistant you trust to act on your behalf.

Security & privacy

You authenticate through Pheidi's normal sign-in — the assistant never receives your credentials.
Every authorization uses PKCE; authorization codes are single-use and short-lived, and refresh tokens rotate on every use.
Access tokens are audience-bound to the /mcp endpoint, so a token issued for MCP can't be replayed against the Plan API (or vice versa).
Every write tool re-checks that the workout or plan belongs to you before changing anything.
The connection only reaches your training data — it can't read other users' plans, and there are no destructive bulk operations.