Model Context Protocol (MCP) Endpoint with Strava Authentication

This implementation establishes a Model Context Protocol (MCP) endpoint capable of remote connections, leveraging integrated Strava OAuth for user sign-in authorization.

Architectural Overview

The core system, built upon Cloudflare Workers, executes dual functions: - Serves as the OAuth Authorization Server for consumer MCP clients. - Acts as the OAuth Client when interacting with Strava's external authorization service.

This repository serves as a didactic example demonstrating how to integrate external OAuth mechanisms within a Cloudflare-hosted MCP server, utilizing the workers-oauth-provider utility.

Prerequisites for Deployment

To proceed, you must possess: - An active Strava user account. - A valid Cloudflare subscription/account. - Local installations of Node.js and npm. - The Wrangler CLI tool (npm install -g wrangler).

Initial Setup Guide

1. Acquire the source code: bash git clone https://github.com/kw510/strava-mcp.git cd strava-mcp npm install

2. Secure your Strava API credentials (refer to the section below on credential configuration).

3. Initialize persistent storage via Cloudflare KV: bash wrangler kv:namespace create "OAUTH_KV"

Update the wrangler.toml configuration file with the newly generated KV namespace identifier.

1. Deploy the service to the Cloudflare edge network: bash wrangler deploy

Configuring Strava API Access Credentials

Production Environment Setup

1. Navigate to Strava's API Application Management portal and register a new application.

2. Define the application parameters:

   • Application Name: A distinct identifier for your integration.
   • Category: Select the most suitable functional classification.
   • Website: The primary URL associated with your service.
   • Application Description: A concise summary of the application's purpose.
   • Authorization Callback Domain: mcp-strava-oauth.<your-subdomain>.workers.dev
   • Authorization Callback URL: https://mcp-strava-oauth.<your-subdomain>.workers.dev/callback

3. Upload sensitive keys as secrets for production deployment: bash wrangler secret put STRAVA_CLIENT_ID wrangler secret put STRAVA_CLIENT_SECRET

Development/Local Testing Setup

1. Create a separate, distinct API application configuration specifically for local testing.

2. Configure the necessary callback endpoints for local execution:

   • Authorization Callback Domain: localhost
   • Authorization Callback URL: http://localhost:8788/callback

3. Establish a .dev.vars file in the root directory to hold local secrets:

STRAVA_CLIENT_ID=your_development_strava_client_id STRAVA_CLIENT_SECRET=your_development_strava_client_secret

Validating the MCP Server Operation

Using the Inspector Client

1. Install the required Inspector utility: bash npx @modelcontextprotocol/inspector@latest

2. Establish connection to the active endpoint:

   • For live deployments: https://mcp-strava-oauth.<your-subdomain>.workers.dev/sse
   • For local testing: http://localhost:8788/sse

Integration with Claude Desktop

1. Access the configuration panel within Claude Desktop: Settings -> Developer -> Edit Config.
2. Append the following configuration block to define the server connection:

{ "mcpServers": { "strava": { "command": "npx", "args": [ "mcp-remote", "https://mcp-strava-oauth..workers.dev/sse" ] } } }

1. Restart Claude Desktop. The initial OAuth negotiation sequence should commence.

Development Workflow

Running Locally

1. Initiate the local development server environment: bash wrangler dev

2. The service will be accessible locally at address http://localhost:8788.

Strava API Request Quotas

Be mindful of the defined usage thresholds for the Strava API: - 200 requests permitted within any 15-minute window. - A daily maximum of 2,000 requests.

Operational Mechanics

The OAuth Provider Layer

This library abstracts and manages crucial server responsibilities, including: - Implementing the full OAuth 2.1 server specification. - Handling the secure issuance and verification of access tokens. - Persistent, secure storage of tokens utilizing the KV store. - Managing the handshake protocol specifically with Strava's OAuth implementation.

The Persistent MCP Component

This module ensures robust session management: - Provides durable context retention across requests. - Securely encapsulates user authentication state. - Enables tool logic to access validated user profiles via this.props. - Allows for conditional activation/deactivation of available tools.

The MCP Remote Interface

This defines the communication backbone: - Handles secure transmission between client and server. - Manages the registration and discovery of available tooling. - Serializes and deserializes request/response payloads. - Maintains the Server-Sent Events (SSE) channel required for real-time updates.

Common Issue Resolution

• Claude Desktop Errors: If errors appear in the desktop application, confirm connectivity by observing the status indicator on the 🔨 icon.
• Cursor Integration: For compatibility with the Cursor editor, utilize the "Command" tool type, concatenating the command and arguments into a single string argument.
• URL Consistency: Verify that the callback URLs registered in your Strava developer application precisely match the deployment URLs.

== Wikipedia Context: XMLHttpRequest (XHR) ==

The XMLHttpRequest (XHR) is a JavaScript object API whose methods facilitate the transmission of HTTP requests from a web browser application to a remote server. These methods permit browser-based code to send queries to the server subsequent to page loading, and to receive data back asynchronously. XHR forms the technical foundation for Asynchronous JavaScript and XML (Ajax) programming patterns. Before Ajax became prevalent, page navigation was primarily controlled by standard hyperlinks and HTML form submissions, which typically necessitated a full page refresh.

== Evolution of XHR ==

The underlying concept for the XMLHttpRequest functionality was first conceived in 2000 by developers working on Microsoft Outlook. This concept was subsequently integrated into Internet Explorer version 5 (released in 1999). However, the initial invocation syntax did not use the standardized XMLHttpRequest identifier. Instead, proprietary ActiveXObject instantiations were employed (ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP")). By the release of Internet Explorer 7 (2006), universal support for the official XMLHttpRequest identifier was established across all major browser rendering engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) officially released a Working Draft specification for the XMLHttpRequest object on April 5, 2006. This was followed by the Level 2 specification Working Draft on February 25, 2008. Level 2 enhancements introduced capabilities for progress monitoring, enabling cross-site data requests, and managing raw byte streams. By the close of 2011, the Level 2 features were incorporated back into the primary specification document. In late 2012, stewardship for the living document transitioned to the WHATWG, which now maintains the specification using Web IDL definitions.

== Standard Usage Pattern == Executing a network request via XMLHttpRequest generally involves several sequential programming actions.

1. Instantiation: Create an instance of the XMLHttpRequest object via its constructor:
2. Configuration: Invoke the "open" method to define the HTTP verb (e.g., GET, POST), specify the target resource URI, and declare whether the operation should be synchronous or asynchronous:
3. Asynchronous Listener: If an asynchronous operation is chosen, register an event handler function to be triggered upon state transitions:
4. Transmission: Command the request to be sent to the server using the "send" method, optionally including payload data:
5. Response Handling: Monitor the state changes within the registered event listener. Upon finalization (state transitioning to 4, the "done" state), the server's response body is typically accessible within the "responseText" property.

Beyond these fundamental steps, XHR offers extensive customization for request control and response processing. Custom HTTP headers can be injected to guide server behavior. Data payloads can be uploaded within the "send" call. Server responses can be parsed directly from JSON into native JavaScript objects, or processed incrementally as they arrive instead of waiting for the complete transmission. Requests can also be terminated prematurely or subject to time-out constraints.

== Inter-Domain Communication Issues ==