> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexrex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect ChatGPT, Claude, Codex, or other AI assistants to your NexRex data.

<Note>
  This is a separate feature from the [Developer API](/api-reference/introduction).
  The Developer API issues organization-scoped keys for building integrations;
  the MCP Server connects your personal account so an AI assistant can query your
  own NexRex training data. If you're building an app or dashboard, see
  [Authentication](/api-reference/authentication) instead.
</Note>

The **MCP Server** (Model Context Protocol, currently in **Beta**) lets AI assistants
such as ChatGPT, Claude, Codex, or Gemini CLI read your NexRex training
data directly inside the tool you already work in.

## What can the AI assistant access?

Once connected, your AI assistant can:

* **Read** your profile, activities, training plans, nutrition logs, recovery data, and race predictions
* **Read** athletes and groups you coach (if you have coach permissions)
* **Draft** training plans and propose workout adjustments
* **Analyze** performance across single athletes or groups

<Warning>
  The AI assistant can **propose** changes to training plans, but **saving or applying changes always requires your explicit approval**. No changes are made to your training calendar without your permission.
</Warning>

## Connection methods

There are two ways to connect:

* **Sign in with NexRex (OAuth)** — recommended for ChatGPT, Claude.ai, and Claude Code. Add the server URL in your client, which triggers a browser sign-in and approval flow. No token to copy.
* **Manual token** — for Codex, Gemini CLI, or other clients without OAuth support. Generate a token in the web console and paste it into your configuration.

<Note>
  **Where does authorization happen?** OAuth approval happens **in your browser** when you add the MCP server in your client (ChatGPT, Claude, etc.). The authorization flow redirects you to NexRex, where you sign in and click **Allow access**.

  **Settings → Integrations** in the NexRex web console is for **manual tokens only**. You won't find an "Authorize" or "Allow access" button there — it only generates tokens for clients that don't support OAuth.
</Note>

***

## Connect ChatGPT

ChatGPT supports OAuth, so you don't need to generate a token manually.

<Steps>
  <Step title="Open custom GPTs settings">
    In ChatGPT, go to your profile settings and select **My GPTs** or **Custom GPTs**.
  </Step>

  <Step title="Add MCP server">
    Click **Configure** or **Add action**, then select **Add MCP server** or similar option.
    (Note: UI labels may vary as ChatGPT evolves.)
  </Step>

  <Step title="Enter the server URL">
    Paste `https://mcp.nexrex.ai/mcp` as the MCP server URL.
  </Step>

  <Step title="Sign in with NexRex">
    ChatGPT opens your browser to the NexRex sign-in page. Sign in with your existing NexRex account.
  </Step>

  <Step title="Approve access">
    Review the consent screen showing the requesting app's name and callback address.
    If the app runs on your own computer, you'll see a warning about a local return address.
    Confirm you initiated this connection, then click **Allow access**.
  </Step>

  <Step title="Start using NexRex in ChatGPT">
    Once connected, you can ask ChatGPT questions about your training data:

    * "Show me my recent activities"
    * "What's my current training plan?"
    * "How am I progressing toward my race goal?"
  </Step>
</Steps>

### Disconnect from ChatGPT

To remove the connection, delete the MCP server from your ChatGPT custom GPT or profile settings. NexRex will revoke the connection's tokens automatically.

***

## Connect Claude

### Claude.ai (web)

Claude.ai supports OAuth connections similar to ChatGPT.

<Steps>
  <Step title="Open integrations">
    In Claude.ai, go to **Settings** → **Integrations** or **Connections**.
  </Step>

  <Step title="Add MCP connection">
    Click **Add connection** or **Add MCP server**, then enter `https://mcp.nexrex.ai/mcp`.
  </Step>

  <Step title="Sign in and approve">
    Your browser opens the NexRex sign-in page. Sign in and click **Allow access** on the consent screen.
  </Step>
</Steps>

### Claude Code (CLI)

Claude Code is a command-line tool that also supports OAuth.

<Steps>
  <Step title="Add the MCP server">
    In your terminal, run:

    ```bash theme={null}
    claude mcp add --transport http nexrex https://mcp.nexrex.ai/mcp
    ```

    <Warning>
      **Do NOT use the `--header "Authorization: Bearer ..."` command** shown in Settings → Integrations if you want OAuth. That command uses a manual token and skips the browser authorization flow entirely. For OAuth, use only the command above without any `--header` flag.
    </Warning>
  </Step>

  <Step title="Authorize the connection">
    Inside Claude Code, run:

    ```bash theme={null}
    /mcp
    ```

    This opens your browser to authorize the connection. Sign in to NexRex and click **Allow access**.
  </Step>

  <Step title="Verify the connection">
    Claude Code will confirm the connection is active. You can now ask questions about your NexRex data.
  </Step>
</Steps>

### Disconnect from Claude

* **Claude.ai**: Remove the connection from Settings → Integrations
* **Claude Code**: Run `claude mcp remove nexrex` in your terminal

***

## Connect Codex

Codex doesn't support OAuth, so you need to generate a manual token from the NexRex web console.

<Steps>
  <Step title="Generate a token in NexRex">
    1. Go to [app.nexrex.ai](https://app.nexrex.ai) and sign in
    2. Navigate to **Settings → Integrations**
    3. Find the **MCP Server** section (marked Beta)
    4. Click **Generate token**

    <Warning>
      The full token is shown **only once**. Copy it immediately — you won't be able to see it again. If you lose it, you'll need to regenerate a new token.
    </Warning>
  </Step>

  <Step title="Copy the Codex configuration">
    On the same page, select the **Codex** tab. Copy the configuration snippet shown:

    ```toml theme={null}
    # ~/.codex/config.toml
    [mcp_servers.nexrex]
    url = "https://mcp.nexrex.ai/mcp"
    http_headers = { "Authorization" = "Bearer YOUR_TOKEN" }
    ```

    Replace `YOUR_TOKEN` with the token you just generated.
  </Step>

  <Step title="Update your Codex config">
    Open or create `~/.codex/config.toml` and paste the configuration with your actual token.
  </Step>

  <Step title="Verify the connection">
    Restart Codex or reload the MCP configuration. Codex should now have access to your NexRex training data.
  </Step>
</Steps>

<Note>
  Use this manual token method when your client doesn't support OAuth, or when you intentionally want to use a token from Settings → Integrations instead of the browser OAuth flow.
</Note>

***

## Connect other clients (Gemini CLI, custom tools)

For clients that don't support OAuth or when you want to use a manual token:

<Steps>
  <Step title="Generate a token in Settings → Integrations">
    1. Sign in to [app.nexrex.ai](https://app.nexrex.ai)
    2. Go to **Settings → Integrations**
    3. In the **MCP Server** section, click **Generate token**
    4. Copy the token immediately (shown only once)
  </Step>

  <Step title="Copy the client-specific config">
    The web console shows tabs for **Claude Code**, **Codex**, and **Gemini CLI**.
    Select your client's tab and copy the configuration snippet. These snippets use manual tokens with the `Authorization: Bearer YOUR_TOKEN` header.
  </Step>

  <Step title="Add to your client's config">
    Follow your client's documentation to add the MCP server URL and token.
    Most clients use a Bearer token header:

    ```
    Authorization: Bearer YOUR_TOKEN
    ```

    Replace `YOUR_TOKEN` with the token you generated.
  </Step>
</Steps>

<Note>
  Use this manual token method when your client doesn't support OAuth (like Codex and Gemini CLI), or when you intentionally want to use a token instead of the OAuth browser flow.
</Note>

***

## Security and tokens

### Token lifetime

* Each manual token has a **creation date** and **expiry date**, shown next to the token's suffix in Settings → Integrations
* There's no separate revoke action — to invalidate a token immediately, regenerate a new one

### Regenerating tokens

<Warning>
  When you regenerate a token, a **new token is issued**. Your previous token keeps working until its expiry date, but the Settings page only tracks the newest one. If you regenerate, update all your AI assistant configurations using the old token.
</Warning>

### Best practices

* **Never commit tokens to version control** — treat them like passwords
* **Don't share tokens** — each token is personal and tied to your NexRex account
* **Regenerate if compromised** — if you accidentally expose a token, regenerate immediately

### OAuth security

OAuth connections use **PKCE** (Proof Key for Code Exchange) and **rotating refresh tokens** for enhanced security. If NexRex detects reuse of an already-rotated refresh token, the entire connection is revoked and you must reconnect.

***

## Using the MCP connection

### Find your own athlete data

The `get_current_user` tool returns the identity of your connected account:

```json theme={null}
{
  "user_id": "usr_8f2k...",
  "athlete_id": "usr_8f2k...",
  "email": "you@example.com",
  "display_name": "Jamie Chen",
  "roles": ["coach"],
  "org_id": "org_x1y2...",
  "profile_available": true
}
```

<Tip>
  **For coaches:** Your own account may not appear in your athlete roster, so roster searches can miss you. Ask your AI assistant to call `get_current_user` first and use the returned `athlete_id` to fetch your own profile, training plan, and activities.
</Tip>

***

## Troubleshooting

### "Authorization failed" or login loop

* **OAuth clients (ChatGPT, Claude)**: Remove the connection and reconnect
* **Manual token clients (Codex, Gemini)**: Regenerate the token in Settings → Integrations and update your configuration

### "Token expired"

Manual tokens have an expiry date. Go to Settings → Integrations and regenerate the token, then update your client configuration.

### "Wrong account" or "Can't see my data"

Make sure you're signed in to the correct NexRex account when authorizing the OAuth connection, or that your manual token was generated from the right account.

### Client doesn't support OAuth

If your AI assistant doesn't offer OAuth or you can't find the MCP connection option, use the **manual token** method instead. Generate a token in Settings → Integrations and follow your client's documentation for adding MCP servers with bearer tokens.