# HYBRD MCP setup (instructions for AI agents)

You are reading this because a person asked you to connect them to HYBRD. Read the whole document before acting.

This document is for AI agents. If you are a person, use the human setup page instead of these instructions. Human setup: https://www.hybrd.com/mcp

## What and why

HYBRD MCP makes it easy to manage and execute your fitness goals. It lets an agent create your fitness plan and workouts, and connect your wearables, so you can track and complete your training wherever works best for you: in HYBRD, where you can log lifting and running, or on your Apple Watch, Garmin, and other connected devices.

Use HYBRD MCP to get guidance grounded in your workout history, ask better questions about what to do next, and turn recommendations into structured workouts and programming. As you complete training, HYBRD automatically adapts the weights and paces prescribed in future sessions. HYBRD MCP gives your AI profile, workout, and connected fitness integration read/write access.

**What this is:** setup instructions for a *remote MCP server*. It is not a Codex skill package, a Claude plugin, an npm package, or a local process. There is nothing to download or install. You add one server entry to the MCP client's configuration, the person signs in to HYBRD in their browser, and then you verify the connection with a tool call.

**Source of truth:** the connected server. After sign-in, `tools/list` is authoritative for tool names, arguments, scopes, and limits. Public docs may lag the server.

## Server

| Field | Value |
| --- | --- |
| Name | `hybrd` |
| URL | `https://mcp.hybrd.com/mcp` |
| Transport | Streamable HTTP (`streamable-http`) |
| Authorization | OAuth 2.1 with dynamic client registration and PKCE S256 |
| Authorization server metadata | https://mcp.hybrd.com/.well-known/oauth-authorization-server |
| API key / env vars / command | None. Remote server; OAuth only. |

Every request, including `tools/list`, requires a signed-in HYBRD account. A 401 before sign-in is expected, not an error.

## Access

HYBRD MCP grants your agent profile, workout, and connected fitness integration read/write access. The person reviews access on the HYBRD consent screen. See `scopes_supported` from the authorization server metadata and the `grantedScopes` returned by `get_account`.

## Procedure

1. **Identify the MCP client** you are running in (ChatGPT, Codex CLI, Claude Code, Claude app, Cursor, VS Code, other) and use the matching section below.
2. **Add the server at user level** (available in every project) unless the person asks for project-level config. Name it `hybrd` and use the URL above.
3. **Start OAuth sign-in.** The client prints or opens a HYBRD sign-in URL. Give that URL to the person and pause until they confirm they approved access.
4. **Verify the account.** Call `get_account`. It returns the connected HYBRD email, approved scopes, and subscription status. 
5. **Confirm subscription.** Connecting is free. Most tools need an active HYBRD subscription. `get_stripe_checkout_link` is only for clients outside ChatGPT/Codex. If `get_account` or `get_profile` onboarding shows no active subscription, or a tool fails with `subscription_inactive`, call `get_stripe_checkout_link` and share the link. Inside ChatGPT or Codex, do not call `get_stripe_checkout_link`; tell the person they need an active HYBRD subscription (they can go to app.hybrd.com). Retry `get_account` after the person subscribes. Do not stop at reporting a missing subscription.
6. **Read the profile.** Call `get_profile`. Complete each onboarding TODO by calling that step's `toolName`, then call `get_profile` again until `onboarding.complete` is true. DEVICE is optional and never blocks complete.
7. **Summarize recent training.** Once the connection and subscription are correct, call `list_workouts` and give the person a quick summary of their last workouts - this is for their 'aha' moment: wow, it really is connected to my wearable(s).

## Client-specific setup

Use the matching block to add the server and finish OAuth. Then continue the Procedure from **Verify the account** (subscription, profile, and a last-workouts summary). Do not stop after adding the server entry.

### Codex CLI

~~~
codex mcp add hybrd --url https://mcp.hybrd.com/mcp
codex mcp login hybrd
codex mcp get hybrd
~~~

This writes a user-level entry to `~/.codex/config.toml`:

~~~toml
[mcp_servers.hybrd]
url = "https://mcp.hybrd.com/mcp"
~~~

`codex mcp login hybrd` prints the HYBRD sign-in URL. After the person approves, `codex mcp get hybrd` should show the enabled remote server and `codex mcp list` should show `hybrd` as authenticated; then call `get_account`. If `get_account` is not available in the current conversation, restart or reconnect Codex before calling it.

### ChatGPT (Codex in the browser)

Settings → MCP servers → Add server. Name `HYBRD`, transport streamable HTTP, URL `https://mcp.hybrd.com/mcp`. Requires a paid ChatGPT plan; on Business/Enterprise/Edu an admin may need to allow custom MCP servers. 

### Claude Code

~~~
claude mcp add --transport http --scope user hybrd https://mcp.hybrd.com/mcp
~~~

`--scope user` stores it in `~/.claude.json` for every project (omit it for the current project only). Then run `/mcp` inside Claude Code, choose `hybrd`, and authenticate; the browser opens the HYBRD sign-in. 

### Claude (desktop or web app)

Customize → Connectors → Add custom connector. Paste `https://mcp.hybrd.com/mcp` and complete the HYBRD sign-in. In a managed organization an owner may need to approve the connector first.

### Cursor

Add to `~/.cursor/mcp.json` (user level) or `.cursor/mcp.json` (project level):

~~~json
{
  "mcpServers": {
    "hybrd": {
      "url": "https://mcp.hybrd.com/mcp"
    }
  }
}
~~~

Then open Cursor Settings → MCP, click sign in next to `hybrd`.

### VS Code (Copilot agent mode)

~~~
code --add-mcp '{"name":"hybrd","type":"http","url":"https://mcp.hybrd.com/mcp"}'
~~~

Or add to the user-profile `mcp.json` (or `.vscode/mcp.json` for one project):

~~~json
{
  "servers": {
    "hybrd": {
      "type": "http",
      "url": "https://mcp.hybrd.com/mcp"
    }
  }
}
~~~

Trust and start the server, sign in to HYBRD in the browser.

### Any other MCP client

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

Field names vary by client; the URL and streamable HTTP transport are what matter. OAuth discovery happens automatically from the server URL.

## Troubleshooting

- **401 / unauthorized on every call:** the OAuth sign-in has not completed. Re-run the client's login step and wait for the person to approve.
- **`get_account` succeeds but a tool reports missing a scope:** explain what the tool needs and ask the person to reconnect the server and approve the matching scope again (`profile`, `workouts`, or `integrations`).
- **No active subscription outside ChatGPT/Codex:** call `get_stripe_checkout_link`, share the link, and retry after checkout. Links expire after 24 hours.
- **No active subscription inside ChatGPT/Codex:** Tell the person they need an active HYBRD subscription (can go to app.hybrd.com) and wait until `get_account` shows one.

## Related

- Human-readable setup page with prompts and deep links: https://www.hybrd.com/mcp
- Tool and scope reference: https://www.hybrd.com/docs/tools