Docs
Back to HYBRD

Developer guide

Connect HYBRD with MCP

Let an MCP-compatible AI create and update structured workouts in HYBRD, where prescribed paces and weights progress automatically from completed training.

What MCP adds

An AI client can generate a training plan on its own. HYBRD's MCP server gives that client a permissioned way to create structured workouts in the system an athlete uses to train, and to read the profile, benchmarks, and coaching context those workouts depend on.

Once workouts are in HYBRD, they can be followed and logged in the mobile app, delivered to supported devices, and connected with completed training from the athlete's fitness apps. HYBRD uses that completed training to automatically update prescribed paces and weights as the athlete gets fitter.

Read access closes the loop: the client can use scheduled workouts, completed sessions, plan intent, profile facts, and benchmarks as context when answering questions or making approved changes to upcoming training.

The division of responsibility

The AI client creates or restructures the plan. HYBRD handles execution, connected training data, and ongoing progression.

Server

HYBRD is a remote MCP server using the Streamable HTTP transport. Configure your client with this endpoint:

MCP endpoint
https://mcp.hybrd.com/mcp

Clients use different configuration files and field names. The JSON below is an illustrative shape, not a copy-and-paste configuration for every client.

Illustrative configuration
{
  "mcpServers": {
    "hybrd": {
      "url": "https://mcp.hybrd.com/mcp",
      "transport": "streamable-http"
    }
  }
}

Authentication

HYBRD uses OAuth 2.1 with dynamic client registration and PKCE S256. A compatible client should discover the authorization server metadata, register as needed, then open the athlete's browser to sign in or create a HYBRD account and approve the requested scopes.

Authorization server metadata
https://mcp.hybrd.com/.well-known/oauth-authorization-server

Protected-resource metadata is published alongside the authorization server metadata. Refresh tokens rotate on every use, so clients must store the newest refresh token returned by a successful refresh.

User approval is required

Authenticate as the athlete whose data the client will read. HYBRD does not receive the client's account credentials, and the client does not receive the athlete's HYBRD password.

Account and subscription setup

No existing HYBRD account is required. HYBRD creates one during the connection flow if needed.

When a tool requires an active subscription, the MCP server returns a secure Stripe checkout link. Complete checkout, then retry the tool.

Scopes

Request only the access the selected tools require. Workout writes are never part of a default read-only grant. The full tool list, scopes, and limits live on the available MCP tools page.

Client checklist

1

Add the remote server

Use the Streamable HTTP endpoint at https://mcp.hybrd.com/mcp.
2

Support OAuth discovery and sign-in

Discover the OAuth metadata, complete dynamic client registration and PKCE S256, and send the athlete through browser-based consent.
3

Request only the access needed

  • profile:read for profile facts, benchmarks, onboarding status, and checkout links
  • profile:write for profile and benchmark updates
  • workouts:read for workouts and plan intent
  • workouts:write for workout creation
4

Handle refreshed credentials

Replace a stored refresh token whenever the authorization server returns a new one.

Security

Access is scoped to the signed-in athlete and the granted OAuth scopes. Read tools return that athlete's training and profile context. Write tools are limited to the approved profile, benchmark, workout, and checkout actions exposed by the server.

It cannot access Brain messages, payment details, or unrelated account data. Treat returned training data as sensitive, request the narrowest scopes needed, and make it clear to athletes when their data will be shared with an AI client.