Installing Pierre MCP Client

Install and configure the Pierre MCP Client SDK for any MCP-compatible application (Claude Desktop, ChatGPT, or custom MCP clients).

Prerequisites

MCP-compatible application installed (Claude Desktop, ChatGPT Desktop, etc.)
Node.js 24+ and npm
Pierre Fitness Platform running (see main README for server setup)

Quick Start

1. Install the SDK

Option A: Install from npm (Recommended)

npm install -g pierre-mcp-client@next

The package is published with the @next tag during v0.x development.

Option B: Use npx (No installation required)

Skip installation and use npx directly in your MCP client configuration.

Option C: Build from source

git clone https://github.com/Async-IO/pierre_mcp_server.git
cd pierre_mcp_server/sdk
npm install
npm run build

2. Start Pierre Fitness Platform

# If you haven't already, start the server
cd pierre_mcp_server
cargo run --bin pierre-mcp-server

The platform will start on port 8081 by default.

3. Configure Your MCP Client

The configuration varies slightly by MCP client but follows the same pattern.

Claude Code caches JWT tokens in memory. If you update the token in ~/.claude.json, you must quit Claude Code completely (Cmd+Q) and relaunch it. Simply reconnecting or closing windows will not clear the cached token.

See Troubleshooting JWT Token Issues for details.

Other MCP Clients

For any MCP-compatible client, use the stdio transport configuration:

{
  "mcpServers": {
    "pierre-fitness": {
      "command": "npx",
      "args": [
        "-y",
        "pierre-mcp-client@next",
        "--server",
        "http://localhost:8081"
      ]
    }
  }
}

If using a locally installed package:

{
  "mcpServers": {
    "pierre-fitness": {
      "command": "pierre-mcp-client",
      "args": [
        "--server",
        "http://localhost:8081"
      ]
    }
  }
}

How It Works

The Pierre MCP Client SDK provides automatic OAuth 2.0 authentication:

Automatic Client Registration: The SDK registers as an OAuth 2.0 client with Pierre using RFC 7591 dynamic client registration
Browser-Based Authentication: Opens your default browser for secure authentication
Token Management: Automatically handles token refresh and storage
Stdio Transport: Provides stdio transport for seamless MCP client integration

No manual JWT token management required!

Testing the Integration

1. Restart Your MCP Client

After updating the configuration, restart your MCP application to load the Pierre MCP Server connection.

2. Verify Connection

Ask your AI assistant:

“What fitness-related tools do you have access to?”

You should see a list of available tools including:

get_activities - Retrieve fitness activities
get_athlete - Get athlete profile
get_stats - Get athlete statistics
analyze_activity - Analyze specific activities
set_goal - Set fitness goals
track_progress - Track goal progress
And 19 more tools…

3. Test Basic Functionality

Try these commands:

Check connection status:

“Check my fitness provider connection status”

Get recent activities:

“Show me my recent workout activities”

Analyze performance:

“Analyze my most recent running activity”

Connecting Fitness Providers

After configuring your MCP client, you need to connect fitness data providers like Strava or Garmin.

Connect to Strava

The SDK will prompt you to connect Strava when you first use fitness tools. Alternatively, you can connect manually:

# Get your JWT token (if needed for direct API access) - OAuth2 ROPC flow
JWT_TOKEN=$(curl -s -X POST http://localhost:8081/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=your@email.com&password=your_password" | jq -r '.jwt_token')

# Get Strava authorization URL
curl "http://localhost:8081/api/oauth/auth/strava/<user_id>" \
  -H "Authorization: Bearer $JWT_TOKEN"

# Open the URL in your browser to authorize

Connect to Garmin

# Get Garmin authorization URL (manual flow)
curl "http://localhost:8081/api/oauth/auth/garmin/<user_id>" \
  -H "Authorization: Bearer $JWT_TOKEN"

# Complete authorization in browser

Verify Connection

curl "http://localhost:8081/api/oauth/status" \
  -H "Authorization: Bearer $JWT_TOKEN"

Troubleshooting

MCP Client Not Connecting

1. Verify Pierre MCP Server is running:

curl http://localhost:8081/health

Expected response: {"status":"healthy","version":"0.2.0"}

2. Check configuration file syntax:

# macOS/Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

# Windows (PowerShell)
Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" | ConvertFrom-Json

3. Check application logs:

Claude Desktop:
- macOS: ~/Library/Logs/Claude/
- Windows: %LOCALAPPDATA%\Claude\logs\
ChatGPT Desktop:
- Check application console/developer tools

SDK Installation Issues

Node.js version too old:

node --version  # Should be 24.0.0 or higher

Update Node.js if needed: https://nodejs.org/

npm permission errors:

# Use npx instead (no installation required)
# Or fix npm permissions:
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

OAuth Flow Not Starting

1. Verify server OAuth configuration:

# Check environment variables
echo $STRAVA_CLIENT_ID
echo $STRAVA_CLIENT_SECRET
echo $STRAVA_REDIRECT_URI

2. Test OAuth endpoint directly:

curl "http://localhost:8081/.well-known/oauth-authorization-server"

Should return server metadata including authorization and token endpoints.

No Fitness Data Available

1. Verify OAuth connection:

curl "http://localhost:8081/api/oauth/status" \
  -H "Authorization: Bearer $JWT_TOKEN"

2. Reconnect provider:

Use the disconnect_provider and connect_provider MCP tools from your AI client, or repeat the manual authorization flow above (/api/oauth/auth/{provider}/{user_id}) to refresh the connection.

JWT Token Caching Issues

Symptoms:

MCP tools return “Unauthorized” error
Config file (~/.claude.json) has correct JWT token
Server logs show authentication failures with old JWT key ID
Error message: Key not found in JWKS: key_20251103_210741

Root Cause:

Claude Code caches JWT tokens at multiple levels:

MCP transport layer (in-memory cache)
MCP connection logs at ~/Library/Caches/claude-cli-nodejs/
Session history at ~/.claude/projects/

Solution:

1. Verify your token is correct:

# Check the key ID in your config file
python3 -c "import base64, json; header = '$(grep "Authorization" ~/.claude.json | grep -o "eyJ[A-Za-z0-9_-]*" | head -1)'; decoded = json.loads(base64.urlsafe_b64decode(header + '==').decode('utf-8')); print('Config kid:', decoded['kid'])"

2. Check server logs for actual key received:

grep "Key not found in JWKS" server.log | tail -1

3. If the key IDs don’t match - Restart Claude Code:

Quit Claude Code completely with Cmd+Q (macOS) or exit all windows
Wait 2-3 seconds
Relaunch Claude Code
The MCP client will re-read ~/.claude.json with the fresh token

Note: Running /mcp reconnect or closing individual windows does NOT clear the JWT cache.

4. Test authentication:

After restarting, test an MCP tool to verify authentication works.

When JWT Tokens Expire:

Pierre MCP Server generates new RSA signing keys on each restart. When this happens:

All existing JWT tokens become invalid
Generate a new JWT token: ./scripts/complete-user-workflow.sh 8081
Update ~/.claude.json with the new token (JWT_TOKEN from .workflow_test_env)
Restart Claude Code completely (Cmd+Q)

Debugging Commands:

# View recent server authentication events
tail -f server.log | grep "JWT authentication\|Key not found"

# Check MCP connection logs
ls -lt ~/Library/Caches/claude-cli-nodejs/-Users-*/mcp-logs-pierre-production/ | head -5

# Verify config file JWT
grep "Authorization" ~/.claude.json | cut -c1-100

Advanced Configuration

Custom Server Port

If Pierre MCP Server is running on a non-standard port:

{
  "mcpServers": {
    "pierre-fitness": {
      "command": "npx",
      "args": [
        "-y",
        "pierre-mcp-client@next",
        "--server",
        "http://localhost:9081"
      ]
    }
  }
}

Custom Server URL

For remote servers:

{
  "mcpServers": {
    "pierre-fitness": {
      "command": "npx",
      "args": [
        "-y",
        "pierre-mcp-client@next",
        "--server",
        "https://pierre.example.com"
      ]
    }
  }
}

Using Installed Package

If you installed globally with npm install -g:

{
  "mcpServers": {
    "pierre-fitness": {
      "command": "pierre-mcp-client",
      "args": [
        "--server",
        "http://localhost:8081"
      ]
    }
  }
}

Using Local Build

If building from source:

{
  "mcpServers": {
    "pierre-fitness": {
      "command": "node",
      "args": [
        "/absolute/path/to/pierre_mcp_server/sdk/dist/cli.js",
        "--server",
        "http://localhost:8081"
      ]
    }
  }
}

Security Considerations

Token Storage

The SDK stores OAuth tokens securely in your user directory:

macOS/Linux: ~/.pierre-mcp-tokens.json
Windows: %USERPROFILE%\.pierre-mcp-tokens.json

HTTPS in Production

For production deployments, always use HTTPS:

{
  "mcpServers": {
    "pierre-fitness": {
      "command": "npx",
      "args": [
        "-y",
        "pierre-mcp-client@next",
        "--server",
        "https://pierre.example.com"
      ]
    }
  }
}

Network Security

Use firewall rules to restrict access to Pierre MCP Server
Enable rate limiting (see server configuration)
Regular security updates for both SDK and server

Getting Help

Documentation

Main README - Server setup and overview
Developer Guide - Complete documentation
API Reference - REST API documentation

Support Channels

GitHub Issues: https://github.com/Async-IO/pierre_mcp_server/issues
Discussions: https://github.com/Async-IO/pierre_mcp_server/discussions

When reporting issues, include:

Operating system and version
MCP client name and version
Node.js version (node --version)
Pierre MCP Server version
Configuration file (sanitize tokens)
Error messages and logs

SDK Command-Line Options

The Pierre MCP Client supports several command-line options:

pierre-mcp-client --help

Options:

--server <url> - Pierre MCP Server URL (required)
--version - Show SDK version
--help - Show help message

What’s Next?

Once you have Pierre MCP Client connected:

Connect fitness providers (Strava, Garmin)
Explore available tools - Ask your AI assistant what it can do
Set fitness goals - Use goal tracking and recommendations
Analyze activities - Get AI-powered insights on your workouts
Track progress - Monitor your fitness journey over time

Version Information

Package: pierre-mcp-client
Current Version: 0.2.0
NPM Tag: next (pre-release)
Minimum Node.js: 24.0.0
License: MIT

Once Pierre reaches v1.0.0, the package will be available on the latest tag:

npm install -g pierre-mcp-client  # Future stable release

Keyboard shortcuts

Pierre Fitness Intelligence