Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ai-cycling-coach review this week's training and replace tomorrow's workout with an easy ride"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A small local stdio MCP server that gives compatible AI agents controlled access to one Intervals.icu account. Intervals.icu remains the source of truth and syncs planned workouts.
In Intervals.icu, open Settings → Developer Settings and generate a personal API key.
Run scripts/setup.sh and enter the key when prompted.
Restart Codex.
Ask Codex to call connection_status before any other operation.
The key is stored only in .env, which is gitignored and set to owner-only
permissions. The setup script creates a local virtual environment and registers
scripts/run-server.sh as a local stdio MCP server named ai-cycling-coach.
Set PYTHON before running setup if you want to use a specific Python 3.11+
interpreter.
Related MCP server: Intervals.icu MCP Server
The server uses standard MCP over stdio, so other MCP clients should be able to
launch the same scripts/run-server.sh command. These integrations have not
been tested yet.
Before registering another client, install the server and create its private environment file from the repository root:
python3.11 -m venv .venv
.venv/bin/python -m pip install -e .
read -r -s -p "Intervals.icu API key: " api_key
printf '\n'
umask 077
printf 'INTERVALS_API_KEY=%s\n' "$api_key" > .env
unset api_key
chmod u+x scripts/run-server.shUse a different Python 3.11+ executable if python3.11 is unavailable.
claude mcp add --scope user ai-cycling-coach -- \
/absolute/path/to/AiCyclingCoach/scripts/run-server.shopenclaw mcp add ai-cycling-coach \
--command /absolute/path/to/AiCyclingCoach/scripts/run-server.sh
openclaw mcp doctor ai-cycling-coach --probeThe DeepSeek API supports tool calling but does not launch local MCP servers by itself. Use DeepSeek through an MCP-capable host, such as OpenClaw, and register the server with that host.
The agent may read training data automatically. Before writing, it must present
the complete plan outline and ask once for approval. Only then may it call
replace_training_plan with approved=true. Configure every MCP client to
require confirmation for this write tool: the server trusts the client's
approved value. The tool can replace only events created with the
ai-cycling-coach: ownership prefix.
Run connection_status first and review the returned athlete identity. The
first calendar write should be a short visible test plan that you explicitly
approve.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| activity_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| newest | Yes | ||
| oldest | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| newest | Yes | ||
| oldest | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| newest | Yes | ||
| oldest | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace integration-owned events after approval of the complete plan.
| Name | Required | Description | Default |
|---|---|---|---|
| newest | Yes | ||
| oldest | Yes | ||
| approved | Yes | ||
| workouts | Yes | ||
| review_note | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does communicate that this operation replaces existing integration-owned events and is gated on approval, but it does not disclose whether the replacement is destructive, how conflicts are handled, or what happens if the approved flag is false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence and front-loads the action, but it is so sparse that it borders on under-specification rather than deliberate conciseness. It earns its place but does not convey enough information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five required parameters and no annotations, the description is not complete enough. It fails to explain what 'oldest' and 'newest' represent, what workouts and review_note contain, how the approval flag controls behavior, and what the replacement scope actually is.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage and the description provides no parameter-level guidance. The five required parameters (oldest, newest, workouts, review_note, approved) are completely unexplained, leaving the agent to guess their meaning and relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Replace') and resource ('integration-owned events'), and adds a precondition ('after approval of the complete plan'). This makes the tool's core action clear, though 'integration-owned events' is somewhat vague without knowing which external system or calendar is involved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should only be used after a plan has been approved, which is useful timing guidance. However, it does not explicitly contrast this tool with alternatives, state when not to use it, or explain what constitutes a 'complete plan'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0connection_statusget_activity_detailsget_athlete_profilelist_activitieslist_calendarlist_wellnessreplace_training_planScored across 7 tools
Each tool targets a distinct resource or level of detail: activities list vs. activity detail, wellness, calendar, athlete profile, connection status, and training plan replacement. There is no meaningful overlap between tool purposes.
The set mostly follows a get_/list_ + noun pattern, which is clear and predictable. Minor deviations are connection_status lacking a verb and the get_ vs. list_ split, but these do not seriously hurt readability.
Seven tools is well-scoped for an AI cycling coach integration, covering athlete data reads and the key plan replacement mutation without unnecessary redundancy.
The core read surfaces for activities, wellness, calendar, and athlete profile are covered, and replace_training_plan provides the key write operation. The main gap is the absence of explicit training-plan creation or approval tools, though the server may assume those happen externally.
Your endurance training data in your AI assistant: activities, recovery, plan, workout edits.
Connect Claude to your Intervals.icu watch data for fitness, workout review, and plan writing.
Access approved FITsociety clients, schedules, bookings and coaching data with AI assistants.
Your strength-training data for any AI assistant: workouts, progress, muscle volume, routines.
