> ## 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. Under **OAuth client**, choose **Use your own OAuth client** and enter the OAuth client ID below. Leave the client secret empty. The other two options (Claude's published identity and automatic registration) are not supported by our sign-in.
    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 five 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`. With `from_current_location`, the assistant's best estimate of where you are.
</ParamField>

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

<Accordion title="Optional parameters">
  <ParamField body="from_current_location" type="boolean" default="false">
    Start the ride from wherever you are now. The route and the map are planned from the approximate origin; the link opens the app's planner with your live location as the start, so you can ask for "a ride from here" without the assistant knowing exactly where you are.
  </ParamField>

  <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>

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.

### geocode

Turns an address, street, postcode, neighbourhood or area name into coordinates inside one of the cities we route in. The assistant uses it for a place it is not sure of before planning the ride.

<ParamField body="query" type="string" required>
  The address or area name, for example `317 S Broadway` or `Abbot Kinney Blvd`.
</ParamField>

<ParamField body="city" type="string" required>
  The city to search in: `london`, `new_york_city`, `los_angeles` or `bay_area`. Results outside it are dropped.
</ParamField>

<Accordion title="Optional parameters">
  <ParamField body="limit" type="integer" default="3">
    How many matches to return, at most 5.
  </ParamField>

  <ParamField body="language" type="string" default="en">
    `en` or `es`: the language of the returned names.
  </ParamField>
</Accordion>

<ResponseField name="results" type="array">
  Each match with `name`, `full_address`, `kind` (`address`, `street`, `postcode`, `neighborhood`, `locality`, `place` or `district`), `lat`, `lng`, and a `context` naming the street, neighbourhood, postcode and city it sits in.
</ResponseField>

### reverse\_geocode

Turns a coordinate into the nearest street, neighbourhood and city. The assistant uses it to describe a point back to you, or to check what a coordinate it was given actually is.

<ParamField body="lat" type="number" required>
  Latitude.
</ParamField>

<ParamField body="lng" type="number" required>
  Longitude.
</ParamField>

<Accordion title="Optional parameters">
  <ParamField body="language" type="string" default="en">
    `en` or `es`.
  </ParamField>
</Accordion>

<ResponseField name="result" type="object">
  The nearest known feature, in the same shape as a `geocode` result.
</ResponseField>

### find\_place

Finds a pub, cafe, shop, park or other venue by name inside one of the cities we route in, and returns its coordinates and address.

<ParamField body="query" type="string" required>
  The venue name alone, for example `Grand Central Market` or `The Brig`. The city bounds the search; adding a neighbourhood or city to the name makes the match drift.
</ParamField>

<ParamField body="city" type="string" required>
  The city to search in: `london`, `new_york_city`, `los_angeles` or `bay_area`.
</ParamField>

<Accordion title="Optional parameters">
  <ParamField body="limit" type="integer" default="3">
    How many matches to return, at most 5.
  </ParamField>

  <ParamField body="language" type="string" default="en">
    `en` or `es`.
  </ParamField>
</Accordion>

<ResponseField name="results" type="array">
  Each match with `name`, `address`, `category` (for example `restaurant` or `park`), `lat` and `lng`.
</ResponseField>

Addresses, areas and venue names are resolved through these lookups, which search only within the city you name. For a well-known landmark the assistant may use its own knowledge, accurate to the block; the planner snaps every place to the nearest road. A lookup answers with a short reason when a name matches nothing in that city.

## 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. The place lookups have their own limits per assistant and a shared hourly budget across all riders. 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.