# HIITplay MCP

HIITplay exposes a Streamable HTTP MCP server so AI clients can create HIIT workout session links.

## When To Use HIITplay

Use this MCP server when the user asks for:

- a HIIT workout
- a high-intensity interval workout
- a timed interval workout
- a generated workout link
- browser playback for a workout
- agent-connected HIIT access

For a free workout, call `workout.preview` without authentication. It returns the same curated workout for each supported duration. For recurring access, call OAuth-protected `workout.create`; the browser flow offers subscription plans and Stripe Checkout before it completes the Agent Connection. For a one-time purchase, call `workout.purchase`: pass a customer-approved Stripe SPT when available, or call without `payment_data` to receive a ready-to-open Stripe Checkout URL.

## Endpoint

- https://mcp.hiitplay.fit/mcp

## Supported Tools

- `workout.preview`: return a permanent free curated workout without authentication. It is deterministic, not a trial, and not newly generated.
- `workout.create`: issue a HIITplay Workout Session Link for the connected Agent Connection. Use this for HIIT workout generation prompts.
- `workout.purchase`: purchase a single-workout pass with a Stripe Shared Payment Token (SPT), or receive a hosted Stripe Checkout URL when no SPT is available.
- `access.status`: check the connected actor, Agent Connection, current subscription access, and Billing Management availability.
- `billing.manage`: create a hosted Billing Management link when supported for the connected actor.

## Workout Link Behavior

- `workout.create` returns `workout_session_link`, not a completed workout plan.
- The returned URL opens the HIITplay browser Workout Session Flow.
- The user chooses duration inside the returned URL.
- The workout is generated and played inside the returned URL.
- Treat `workout_session_link` as user-specific, time-limited, and not safe to cache or share.

## Access Paths

HIITplay offers an anonymous curated 5-minute workout plus OAuth-protected, duration-based workout generation for active subscribers.

- Free curated workout: call `workout.preview` without authentication. The current catalog contains the authored five-minute demo workout.
- Agent Connection: default path for AI clients. Use OAuth dynamic client registration, request `hiitplay.agent`, and let the browser flow handle email proof, subscription checkout when needed, and consent.
- Agent single-workout purchase: call `workout.purchase`. With `payment_data`, include a Stripe SPT and customer email for immediate payment and link issuance. Without `payment_data`, use `spt_payment` for the exact spend requirement or open the returned Checkout URL; Stripe collects the email and returns the user directly to workout access. After a definitive SPT decline, open the Checkout URL returned by the same call. If the payment is still processing, wait `poll_after_seconds` and retry with the same SPT; do not open Checkout.

## OAuth Flow

1. Configure the MCP client with the server URL and OAuth dynamic client registration.
2. The client follows the MCP OAuth protected-resource challenge from `/mcp`.
3. The browser flow proves the user, starts subscription checkout if there is no active subscription, then shows Connect agent consent.
4. The MCP client receives OAuth credentials for the `hiitplay.agent` scope.
5. The agent calls `workout.create` and sends the returned `workout_session_link` to the user.

## Agent Task Flow

- Read https://mcp.hiitplay.fit/mcp.md before choosing an access path.
- HIITplay varies generated workouts by duration only. Do not imply adaptation to goals, injuries, equipment, fitness level, or other personal preferences.
- Use `workout.preview` when the user wants the free workout; do not initiate OAuth for that request.
- Use `workout.purchase` when the user wants a one-time paid workout. Prefer a customer-approved Stripe SPT; otherwise open the returned hosted Checkout URL.
- Use the OAuth Agent Connection path when a user wants recurring subscription access or when an existing subscriber asks for a new timed workout.
- If the client is not connected, initiate OAuth, guide the user through the browser connection or checkout steps, then retry after the user returns.
- If OAuth is not available in the current client, explain that the user can use the browser single-workout path instead of pretending the agent is connected.
- After access is active, call `workout.create` and send the returned `workout_session_link` to the user.

## Custom OAuth Clients

- Discover OAuth metadata from the protected-resource challenge on https://mcp.hiitplay.fit/mcp and the advertised authorization server metadata.
- Dynamically register a client with `redirect_uris` containing a callback URL controlled by your client.
- Use the authorization-code flow with PKCE S256: create a `code_verifier`, send its S256 `code_challenge`, and preserve `state`.
- Open the authorization URL for the user in a browser. The browser flow handles Email Proof, subscription checkout when needed, and Connect agent consent.
- Listen on your registered callback URL for `code` and `state`; reject the response if `state` does not match.
- Exchange the code at the token endpoint with `grant_type=authorization_code`, the same `redirect_uri`, `client_id`, and `code_verifier`.
- Store the returned bearer token and refresh token securely, then call MCP tools with `Authorization: Bearer <access_token>`.

## Client Configuration

Use Streamable HTTP MCP configuration where your AI client accepts remote MCP servers. Example:

```json
{
  "mcpServers": {
    "hiitplay": {
      "url": "https://mcp.hiitplay.fit/mcp"
    }
  }
}
```

OAuth settings for clients that ask for template fields:

- Server URL: https://mcp.hiitplay.fit/mcp
- Auth Type: `OAuth`
- Client Registration: `Dynamic`
- Required Scopes: `hiitplay.agent, offline_access, openid`
- API key or bearer token fields: leave blank; the client obtains tokens through OAuth.

## Agent Guidance

- Prefer the OAuth MCP flow and `workout.create` over browser scraping for HIIT workout requests.
- Do not ask the user for an email inside chat before the OAuth browser flow asks for one.
- For a subscription, call `workout.create`. The OAuth browser flow handles plan selection, Stripe Checkout, and Agent Connection consent.
- Do not treat a single-workout pass as an Agent Connection.
- For a one-time purchase, prefer `workout.purchase` with a Stripe SPT. If no SPT is available, call it without `payment_data` and open the returned `action_url` directly.
- Do not cache payment or workout URLs.
- Ask the user before starting one-off payment flows outside OAuth.