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

# Connect Cyclemate to Claude

> Plan SuperSafe rides from Claude or ChatGPT with your own Cyclemate account

## Overview

Cyclemate is available as a connector for AI assistants. Once connected, you can ask Claude or ChatGPT for a ride in plain words, for example "plan me a Sunday loop from Angel through five parks", and the assistant plans it with our SuperSafe routing, shows you a map, and gives you a link that opens the ride in the Cyclemate app.

The connector uses your own Cyclemate account. You sign in once, approve the assistant, and every ride it plans is attributed to you and counts against your account's limits. The assistant never sees your email address, your home or work address, your ride history or your saved routes.

Connecting an assistant needs [Cyclemate Premium](https://cyclemate.club/premium).

The connector address is:

```text theme={null}
https://api.cyclemate.club/mcp
```

It speaks the Model Context Protocol over HTTP, so any assistant that supports remote MCP connectors with OAuth sign-in can use it.

## Add the connector

<Tabs>
  <Tab title="Claude">
    1. Open Claude on the web or in the desktop app and go to **Settings**, then **Connectors**.
    2. Choose **Add custom connector**.
    3. Enter `Cyclemate` as the name and `https://api.cyclemate.club/mcp` as the URL.
    4. Open **Advanced settings** and enter the OAuth client ID below. Leave the client secret empty.
    5. Choose **Add**, then **Connect**. Your browser opens the Cyclemate sign-in page. Sign in if you need to, then choose **Allow**.

    OAuth client ID for Claude:

    ```text theme={null}
    a011cdd9-0bdd-4b19-b4a7-cee9e6e3fc26
    ```
  </Tab>

  <Tab title="ChatGPT">
    1. In ChatGPT, open **Settings**, then **Apps and connectors**, and turn on **Developer mode** under **Advanced settings**.
    2. Choose **Create** and enter `Cyclemate` as the name and `https://api.cyclemate.club/mcp` as the MCP server URL.
    3. Under the OAuth settings, enter the OAuth client ID below. No client secret is needed.
    4. Save, then connect. Your browser opens the Cyclemate sign-in page. Sign in if you need to, then choose **Allow**.

    OAuth client ID for ChatGPT:

    ```text theme={null}
    CHATGPT_CLIENT_ID
    ```
  </Tab>

  <Tab title="Claude Code">
    Add the server, then run `/mcp` to sign in:

    ```bash theme={null}
    claude mcp add --transport http cyclemate https://api.cyclemate.club/mcp
    ```

    When Claude Code asks for OAuth client credentials, use the Claude client ID `a011cdd9-0bdd-4b19-b4a7-cee9e6e3fc26` with no secret.
  </Tab>
</Tabs>

If you are not a Premium member, the sign-in page says so and offers the upgrade instead of **Allow**.

## What the assistant can do

The connector offers two tools. The assistant chooses when to call them.

### whoami

Returns who the assistant is acting for: your display name and handle, the city and units saved in your account, whether you have Premium, and the cities Cyclemate routes in, each with a centre coordinate. No email address and no coordinates of your own places.

### plan\_ride

Plans a ride and returns the route options, a map image, and the link that opens the ride in Cyclemate.

<ParamField body="origin" type="object" required>
  The start: `name`, `lat`, `lng`.
</ParamField>

<ParamField body="destination" type="object" required>
  The end: `name`, `lat`, `lng`.
</ParamField>

<Accordion title="Optional parameters">
  <ParamField body="stops" type="array">
    Up to eight places to ride through, in order, each with `name`, `lat`, `lng`. Every place in one ride must be in the same city.
  </ParamField>

  <ParamField body="departure_time" type="string">
    Wall-clock departure in the ride's city, `YYYY-MM-DDTHH:mm`. Omit to leave now. After dark the ride prefers well-lit streets in cities with night routing.
  </ParamField>

  <ParamField body="supersafe" type="boolean" default="true">
    Open the link on the SuperSafe route. The response always carries both the SuperSafe and the Direct option.
  </ParamField>

  <ParamField body="language" type="string" default="en">
    `en` or `es`: the language of the route's labels.
  </ParamField>

  <ParamField body="include_map" type="boolean" default="true">
    Attach a map image of the SuperSafe route.
  </ParamField>
</Accordion>

The response the assistant reads:

<ResponseField name="options" type="array">
  One entry per route option (SuperSafe and Direct; at night also the day variant), each with `label`, `distance_m`, `duration_s`, `elevation_gain_m`, `quiet_pct` (the share of the ride on quiet roads or cycleways), `avoided` (busy streets, closures and restrictions the SuperSafe route steered around), `disruptions`, and one `legs` entry per stop with `to`, `starts_on` (the road the leg sets off on), `distance_m` and `duration_s`.
</ResponseField>

<ResponseField name="open_url" type="string">
  The link to give the rider. On a phone with Cyclemate installed it opens the app's planner with every stop in place; elsewhere it opens the web planner.
</ResponseField>

<ResponseField name="app_url" type="string">
  The same ride as a `com.cyclemate.app://` link, for a client that wants the app explicitly.
</ResponseField>

<ResponseField name="embed_url" type="string">
  An interactive map of the ride for embedding on a page.
</ResponseField>

<ResponseField name="search_id" type="string">
  The id of the planned ride on our side.
</ResponseField>

The assistant supplies the coordinates of the places it picks. For a well-known place they are accurate to the block, and the planner snaps each to the nearest road. For a small venue or an exact address, give the assistant the address or the coordinates yourself.

A ride is refused with a short reason when a place is outside the cities we route in, when the places span two cities, when two consecutive places are the same spot, or when the account has planned too many rides in a short time.

## Limits

The connector plans rides through the same service as the app, so [the ride planner's limits](/api-reference/routing/multimodal) apply to your account, counted per assistant. When a limit is hit the assistant is told how long to wait.

## Disconnect

Open **Account**, then **Settings**, then **Connected apps**, and choose **Disconnect** next to the assistant. It loses access straight away and has to sign in again before it can plan rides as you. In the app, the same row in Settings opens this page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.