SPECIFICATION · MCP REFERENCE

Primed Model Context Protocol
(MCP) Server.

Canonical endurance coaching intelligence for AI assistants, agent frameworks, and athlete applications.

Specification v1.0.0Streamable HTTP & SSEOAuth 2.1 (PKCE)100% Read-OnlyUpdated October 2026

Server EndpointPOSThttps://mcp.beprimed.ai/mcp

SECTION 01

1. Overview & Purpose

Primed is an evidence-grounded endurance coaching intelligence platform for self-directed athletes (runners, cyclists, and triathletes).

The Primed MCP Connector provides an authenticated, read-only interface allowing AI assistants (such as Meta Muse, Claude, and OpenAI ChatGPT) to access an athlete's canonical coaching decisions, planned training schedules, athletic recovery states, and completed activities.

Key Architectural Invariants

Canonical Coaching Authority: All coaching decisions, session adaptations, and recovery evaluations originate from Primed’s deterministic coaching engine (DailyCoachingDecisionService). The AI assistant consumes and explains these decisions; it does not independently compute or invent workouts.
100% Read-Only V1 Contract: The connector contains zero mutation or deletion tools. It does not alter training calendars, modify athlete accounts, or execute financial transactions.
Zero Split-Brain: All connected surfaces (native apps, web client, and MCP connectors) consume identical canonical records. Dual-writes, out-of-band mutations, and unversioned fallbacks are strictly prohibited.
Non-PHI & Data Minimization: Exposes only high-level athletic training parameters and classifications. Collects no Protected Health Information (PHI), clinical diagnostic data, or raw continuous biometric streams (such as raw ECG or HRV tachograms).

Intended Coaching Lifecycle

evidence → judgement → canonical decision/DCD → authorised mutation → verified persistence → athlete-facing presentation → independent verification

SECTION 02

2. Authentication & Authorization

The Primed MCP server requires OAuth 2.1 authentication on all tool endpoints.

OAuth 2.1 Authorization Server: https://auth.beprimed.ai/
OAuth Protected Resource Metadata: https://mcp.beprimed.ai/.well-known/oauth-protected-resource
Token Format: Bearer JSON Web Token (JWT) signed with RS256, validated against Primed JWKS.
Tenant Isolation: Every request binds strictly to the sub (athlete user ID) claim verified in the JWT. Cross-athlete or unauthorized data queries are rejected at the protocol layer.

Supported OAuth Scopes

All supported scopes are strictly limited to read operations:

Scope	Description	Sensitivity
`primed:profile:read`	Read connected athlete display name, primary sport, and timezone	Low
`primed:coaching:read`	Read today's canonical Daily Coaching Decision (DCD) and adaptation reasoning	Medium
`primed:training:read`	Read upcoming scheduled workouts and training plan calendar	Low
`primed:activities:read`	Read recent completed training session volume and activity summaries	Low

SECTION 03

3. Tool Specifications & Classification

In accordance with Section 3 and Section 5.4 of the Muse Platform Connector Guidelines, all Primed tools are classified below.

Summary Table

Tool Name	Classification	Sensitive Designation	Required Scope(s)	Side Effects
`get_primed_profile`	Read	No	`primed:profile:read`	None
`get_today_coaching`	Read	No	`primed:coaching:read`	None
`get_upcoming_training`	Read	No	`primed:training:read`	None
`get_training_status`	Read	No	`primed:coaching:read` or `primed:training:read`	None
`get_recent_activity_summary`	Read	No	`primed:activities:read`	None

Tool 1: get_primed_profile

ReadNon-Sensitive

Identifies the connected Primed athlete account and provides essential non-sensitive context to anchor the conversation.

Classification: Read
Required Scope: primed:profile:read
Side Effects: None

Input Schema

get_primed_profile Input Schemajson

{}

Output Fields

profile_id (string): Pseudonymous athlete identifier.
display_name (string): Athlete display name.
timezone (string): IANA timezone identifier (e.g. Australia/Perth).
primary_sport (string): Main athletic discipline (cycling, running, triathlon).
account_status (string): Subscription/account status (active, trial).

Tool 2: get_today_coaching

ReadNon-Sensitive

Retrieves today’s canonical Daily Coaching Decision (DCD) and scheduled session for the athlete’s local date, including evidence-grounded adaptation reasons if the planned workout was adjusted.

Classification: Read
Required Scope: primed:coaching:read
Side Effects: None

Input Schema

get_today_coaching Input Schemajson

{
  "date": "2026-10-14"
}

* date (string, optional): Local date in YYYY-MM-DD format (defaults to current day in athlete's timezone).

Output Fields

date (string): Local date of the decision.
timezone (string): Athlete's local timezone.
decision_id (string): Canonical decision identifier.
action_type (string): Prescribed action (execute_as_planned, adapt_session, substitute_recovery, rest).
session (object, optional): Workout specification:
- title (string): Name of the session (e.g. "Aerobic Base Ride").
- sport (string): Sport discipline.
- duration_minutes (number): Target duration in minutes.
- target_intensity (string): Prescribed intensity tier (e.g. Z2 - Aerobic Endurance).
- description (string): Session goals and coaching notes.
- intervals (array of objects, optional): Interval steps and power/pace targets.
changed_from (object, optional): Original planned session details if modified.
reason_summary (string, optional): Plain-English explanation of adaptation (e.g. "Adjusted due to sleep duration below baseline and elevated recovery strain").
reason_codes (array of strings): Canonical reason tags (e.g. ["sleep_below_baseline", "recovery_amber"]).
freshness (object): ISO timestamps of decision generation and underlying data synchronization.

Tool 3: get_upcoming_training

ReadNon-Sensitive

Retrieves upcoming scheduled training sessions from the athlete’s training plan.

Classification: Read
Required Scope: primed:training:read
Side Effects: None

Input Schema

get_upcoming_training Input Schemajson

{
  "start_date": "2026-10-14",
  "days": 7
}

* start_date (string, optional): Starting local date in YYYY-MM-DD format (defaults to today).
* days (integer, optional): Number of days forward to inspect (1 to 14, default 7).

Output Fields

start_date (string): Range start date.
end_date (string): Range end date.
timezone (string): Athlete's local timezone.
sessions (array of objects): Scheduled workouts:
- date (string): Scheduled date (YYYY-MM-DD).
- sport (string): Sport discipline.
- title (string): Workout name.
- duration_minutes (number, optional): Target duration.
- description (string, optional): Session overview.

Tool 4: get_training_status

ReadNon-Sensitive

Returns a high-level snapshot of the athlete’s athletic training load, readiness tier, and key physiological/training drivers without exposing raw medical records.

Classification: Read
Required Scopes: primed:coaching:read or primed:training:read
Side Effects: None

Input Schema

get_training_status Input Schemajson

{
  "as_of": "2026-10-14T08:00:00Z"
}

* as_of (string, optional): ISO 8601 timestamp (defaults to current time).

Output Fields

as_of (string): Timestamp of evaluation.
training_state (string): Training phase classification (productive, maintaining, peaking, recovery, overloaded).
recovery_status (string): High-level readiness tier (green, amber, red).
load_status (string): Chronic/acute training load balance classification (optimal, elevated, low).
drivers (array of objects): Key coaching factors influencing current readiness (e.g. summary: "Recent 7-day training volume +18% above rolling baseline").
data_freshness (string): Timestamp of latest synchronized wearable data.

Tool 5: get_recent_activity_summary

ReadNon-Sensitive

Summarizes recent completed workouts and training volume for the athlete to evaluate compliance and consistency.

Classification: Read
Required Scope: primed:activities:read
Side Effects: None

Input Schema

get_recent_activity_summary Input Schemajson

{
  "days": 7
}

* days (integer, optional): Number of past days to inspect (1 to 28, default 7).

Output Fields

period (object): start_date and end_date of the summary window.
summary (object):
- completed_sessions (number): Total completed workouts.
- total_duration_minutes (number): Total moving time.
- sports (array of strings): Disciplines completed during the period.
activities (array of objects): List of completed workouts with date, sport, title, duration, and distance.

SECTION 04

4. Error Handling & Status Codes

All errors conform to RFC 7807 problem details and standardized MCP error payloads with machine-readable canonical codes:

RFC 7807 JSON-RPC Error Payload Examplejson

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Authentication required to access today coaching decision",
    "data": {
      "code": "UNAUTHENTICATED",
      "message": "Authentication required to access today coaching decision"
    }
  },
  "id": 1
}

Canonical Error Codes

Error Code	HTTP Status	Meaning	Recovery Action
`UNAUTHENTICATED`	401	Missing or invalid OAuth Bearer token	Re-authenticate via OAuth flow
`INSUFFICIENT_SCOPE`	403	Token lacks required scope for tool	Request consent for the required scope
`FORBIDDEN`	403	Athlete account suspended or restricted	Contact Primed support
`INVALID_ARGUMENT`	400	Argument validation failure (e.g. malformed date)	Check input formats and retry
`NO_DATA`	200 / 404	No coaching decision or workouts recorded for period	Rest day or onboarding pending
`STALE_DATA`	200	Wearable sync delayed; cached decision returned	Advise user to sync wearable
`RATE_LIMITED`	429	Rate limit exceeded	Back off and retry after cooldown
`DEPENDENCY_UNAVAILABLE`	503	Upstream service temporarily unavailable	Retry after brief delay
`UNSUPPORTED_OPERATION`	400	Client requested write/mutation in read-only V1	Advise user that V1 is read-only

SECTION 05

5. Rate Limits & Quotas

To ensure service reliability and prevent accidental client looping:

Standard Quota: 60 requests per minute per authenticated athlete token.
Burst Allowance: Up to 10 concurrent requests.
Exceeded Limits: Returns HTTP 429 Too Many Requests with a standard Retry-After header and canonical code RATE_LIMITED.

Recommended Client Retry Strategy

Clients should parse the Retry-After HTTP header and apply exponential backoff with jitter (minimum 1.5x backoff factor) when receiving a 429 response.

SECTION 06

6. Privacy, Security & Compliance

Data Protection Safeguards

Encryption in Transit: All traffic is strictly enforced over TLS 1.3.
Encryption at Rest: All persisted data is encrypted with AES-256.
Zero Model Training on Athlete Data: Data processed through the Primed MCP connector is never used to train foundational AI models, sold to third parties, or used for advertising.
Data Minimization: Only requested fields are transmitted.
Token Revocation: When an athlete disconnects the connector in Muse or Primed, OAuth tokens are revoked immediately, preventing any subsequent access.

Health Boundaries (Non-PHI)

Primed is an athletic training intelligence platform, not a medical provider. The MCP tools:

Do NOT diagnose medical symptoms or clinical conditions (e.g. chest pain, cardiac anomalies).
Do NOT process or expose Protected Health Information (PHI) under HIPAA or health records under GDPR.
Direct athletes to seek immediate professional medical attention in the event of injury or health distress.

Security Incident Reporting (Meta Policy § 4.8)

In compliance with Meta Muse Connector Platform requirements, any confirmed security incident involving user data will be escalated to Meta at vendor-incident@meta.com within 48 hours.

Security Inquiries

security@beprimed.ai

Platform Support

support@beprimed.ai · Help Desk

SECTION 07

7. Client Configuration & Quickstarts

Connect your favorite MCP-compatible agent or client directly to the Primed MCP Server.

Claude Desktop Configuration

Add the following to your claude_desktop_config.json file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

claude_desktop_config.jsonjson

{
  "mcpServers": {
    "primed": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://mcp.beprimed.ai/mcp"
      ],
      "env": {
        "PRIMED_BEARER_TOKEN": "YOUR_OAUTH_BEARER_TOKEN"
      }
    }
  }
}

Direct HTTP / SSE Query with Curl

Test tool invocation directly using standard JSON-RPC over Streamable HTTP:

cURL JSON-RPC Examplebash

curl -X POST https://mcp.beprimed.ai/mcp \
  -H "Authorization: Bearer $PRIMED_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_today_coaching",
      "arguments": {}
    }
  }'

← Back to Developer Documentation Overview

On this page