MCP Server

Rhumby provides a Model Context Protocol (MCP) server that lets AI assistants like Claude query race data, look up standings, and manage registrations.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to interact with external data sources and tools. By running the Rhumby MCP server, you can ask Claude (or other MCP-compatible AI assistants) questions like:

"What regattas are happening this weekend?"
"Show me the standings for the Summer Series"
"Register my boat for the Spring Invitational"

The AI assistant will use the MCP tools to query the Rhumby API and return results in natural language.

Quick Start

Prerequisites

Node.js 18 or higher
A Rhumby API key (get one from your account settings)

Installation

The MCP server is included in the Rhumby repository. Clone it and install dependencies:

git clone https://github.com/yourusername/rhumby.git
cd rhumby
npm install

Configuration

Set your API key and base URL as environment variables:

export RHUMBY_API_KEY=rhb_your_key_here
export RHUMBY_BASE_URL=https://api.rhumby.com

For local development, you can use http://localhost:3000 as the base URL.

Running the Server

npm run mcp

The server runs on stdio (standard input/output) and communicates using JSON-RPC 2.0.

Connecting Claude Desktop (recommended: custom connector)

Rhumby hosts a remote MCP server at https://rhumby.com/api/mcp with OAuth 2.1 authorization, so the easiest way to connect Claude Desktop is via the custom connector UI — no local config file, no API key to manage.

Open Claude Desktop → Settings → Connectors → Add custom connector
Enter the MCP server URL: https://rhumby.com/api/mcp
Click Connect. Claude will open a Rhumby consent page in your browser.
Sign in with your Rhumby account (if you aren't already) and approve the connection.
Back in Claude Desktop, the Rhumby tools will now be available. Try asking "What regattas are coming up?"

Behind the scenes Claude Desktop performs RFC 7591 Dynamic Client Registration, drives an OAuth 2.1 authorization-code flow with PKCE (S256), and stores the resulting refresh token. You can revoke access at any time from your Rhumby account settings.

Advanced: local stdio server

The stdio server is still available for local development or when you can't use the hosted remote server. It authenticates with a personal rhb_... API key rather than OAuth:

Open your Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the Rhumby server configuration:

{
  "mcpServers": {
    "rhumby": {
      "command": "npx",
      "args": ["tsx", "/path/to/rhumby/src/mcp/server.ts"],
      "env": {
        "RHUMBY_API_KEY": "rhb_your_key_here",
        "RHUMBY_BASE_URL": "https://api.rhumby.com"
      }
    }
  }
}

Restart Claude Desktop.

Available Tools

The MCP server exposes the following tools:

search_events

Find regattas by name, status, date, or organization.

Parameters:

query (optional): Search query for event name
status (optional): Filter by status — published, ongoing, or completed
after (optional): Events after this date (YYYY-MM-DD)
before (optional): Events before this date (YYYY-MM-DD)
org (optional): Filter by organization slug
limit (optional): Maximum number of results

Example:

"Show me all ongoing regattas in the next 30 days"

get_event

Get full details for a specific event including races and registration count.

Parameters:

slug (required): Event slug identifier

Example:

"Tell me about the spring-invitational-2025 event"

get_standings

Get current standings table for an event or series.

Parameters:

slug (required): Event slug identifier

Example:

"What are the standings for the summer-series?"

get_results

Get race results for an event (all races or a specific race).

Parameters:

slug (required): Event slug identifier
race_id (optional): Specific race ID for individual race results

Example:

"Show me the results from yesterday's race"

list_organizations

Browse yacht clubs and sailing organizations.

Parameters:

query (optional): Search query for organization name

Example:

"Find yacht clubs in Florida"

register_boat

Parameters:

slug (required): Event slug identifier
boat_name (required): Name of the boat
boat_class (required): Boat class (e.g., J/70, Melges 24)
sail_number (required): Sail number
skipper_name (required): Skipper's full name
skipper_email (required): Skipper's email address

Example:

"Register my J/70 'Fast Forward' with sail number USA 123 for the spring regatta"

get_sailor_history

Look up a sailor's race history and statistics.

Parameters:

sailor_id (required): Sailor ID or username

Example:

"What's John Smith's racing record?"

list_series

Browse racing series.

Parameters:

limit (optional): Maximum number of results

Example:

"Show me all racing series"

Available Resources

The MCP server also exposes browseable resources:

rhumby://events — List of current events
rhumby://events/{slug} — Detailed information about a specific event
rhumby://organizations — List of yacht clubs and sailing organizations

Resources provide read-only access to Rhumby data and can be referenced by AI assistants for context.

Development

Project Structure

src/mcp/
├── server.ts        # Main MCP server with tool handlers
└── api-client.ts    # HTTP client for Rhumby API

Adding New Tools

To add a new tool:

Define the input schema using Zod in server.ts
Add the tool definition to the ListToolsRequestSchema handler
Implement the tool logic in the CallToolRequestSchema handler
Format the response as readable text (not raw JSON)

Error Handling

All tools handle errors gracefully and return error messages as text. The server never crashes on API errors — it returns a formatted error response that the AI assistant can present to the user.

Troubleshooting

"API error: 401"

Your API key is invalid or missing. Check that RHUMBY_API_KEY is set correctly.

"API error: 404"

The requested resource (event, organization, etc.) doesn't exist. Double-check the slug.

"ECONNREFUSED"

The Rhumby API server is not running or RHUMBY_BASE_URL is incorrect. For local development, make sure the Next.js dev server is running on http://localhost:3000.

Claude Desktop doesn't see the tools

Check that claude_desktop_config.json is valid JSON
Verify the path to server.ts is absolute and correct
Restart Claude Desktop completely (Quit, not just close the window)
Check Claude Desktop logs (Help → View Logs)

Security

API Keys: Never commit API keys to version control. Use environment variables.
Rate Limits: The MCP server respects Rhumby API rate limits. Excessive requests may be throttled.
Access Control: MCP tools use the same permissions as your API key. If your key has read-only access, you won't be able to register boats or modify data.

Learn More

Rhumby provides a Model Context Protocol (MCP) server that lets AI assistants like Claude query race data, look up standings, and manage registrations.

What is MCP?

"What regattas are happening this weekend?"
"Show me the standings for the Summer Series"
"Register my boat for the Spring Invitational"

The AI assistant will use the MCP tools to query the Rhumby API and return results in natural language.

Quick Start

Prerequisites

Node.js 18 or higher
A Rhumby API key (get one from your account settings)

Installation

The MCP server is included in the Rhumby repository. Clone it and install dependencies:

git clone https://github.com/yourusername/rhumby.git
cd rhumby
npm install

Configuration

Set your API key and base URL as environment variables:

export RHUMBY_API_KEY=rhb_your_key_here
export RHUMBY_BASE_URL=https://api.rhumby.com

For local development, you can use http://localhost:3000 as the base URL.

Running the Server

npm run mcp

The server runs on stdio (standard input/output) and communicates using JSON-RPC 2.0.

Connecting Claude Desktop (recommended: custom connector)

Open Claude Desktop → Settings → Connectors → Add custom connector
Enter the MCP server URL: https://rhumby.com/api/mcp
Click Connect. Claude will open a Rhumby consent page in your browser.
Sign in with your Rhumby account (if you aren't already) and approve the connection.
Back in Claude Desktop, the Rhumby tools will now be available. Try asking "What regattas are coming up?"

Advanced: local stdio server

The stdio server is still available for local development or when you can't use the hosted remote server. It authenticates with a personal rhb_... API key rather than OAuth:

Open your Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the Rhumby server configuration:

{
  "mcpServers": {
    "rhumby": {
      "command": "npx",
      "args": ["tsx", "/path/to/rhumby/src/mcp/server.ts"],
      "env": {
        "RHUMBY_API_KEY": "rhb_your_key_here",
        "RHUMBY_BASE_URL": "https://api.rhumby.com"
      }
    }
  }
}

Restart Claude Desktop.

Available Tools

The MCP server exposes the following tools:

search_events

Find regattas by name, status, date, or organization.

Parameters:

query (optional): Search query for event name
status (optional): Filter by status — published, ongoing, or completed
after (optional): Events after this date (YYYY-MM-DD)
before (optional): Events before this date (YYYY-MM-DD)
org (optional): Filter by organization slug
limit (optional): Maximum number of results

Example:

"Show me all ongoing regattas in the next 30 days"

get_event

Get full details for a specific event including races and registration count.

Parameters:

slug (required): Event slug identifier

Example:

"Tell me about the spring-invitational-2025 event"

get_standings

Get current standings table for an event or series.

Parameters:

slug (required): Event slug identifier

Example:

"What are the standings for the summer-series?"

get_results

Get race results for an event (all races or a specific race).

Parameters:

slug (required): Event slug identifier
race_id (optional): Specific race ID for individual race results

Example:

"Show me the results from yesterday's race"

list_organizations

Browse yacht clubs and sailing organizations.

Parameters:

query (optional): Search query for organization name

Example:

"Find yacht clubs in Florida"

register_boat

Parameters:

slug (required): Event slug identifier
boat_name (required): Name of the boat
boat_class (required): Boat class (e.g., J/70, Melges 24)
sail_number (required): Sail number
skipper_name (required): Skipper's full name
skipper_email (required): Skipper's email address

Example:

"Register my J/70 'Fast Forward' with sail number USA 123 for the spring regatta"

get_sailor_history

Look up a sailor's race history and statistics.

Parameters:

sailor_id (required): Sailor ID or username

Example:

"What's John Smith's racing record?"

list_series

Browse racing series.

Parameters:

limit (optional): Maximum number of results

Example:

"Show me all racing series"

Available Resources

The MCP server also exposes browseable resources:

rhumby://events — List of current events
rhumby://events/{slug} — Detailed information about a specific event
rhumby://organizations — List of yacht clubs and sailing organizations

Resources provide read-only access to Rhumby data and can be referenced by AI assistants for context.

Development

Project Structure

src/mcp/
├── server.ts        # Main MCP server with tool handlers
└── api-client.ts    # HTTP client for Rhumby API

Adding New Tools

To add a new tool:

Define the input schema using Zod in server.ts
Add the tool definition to the ListToolsRequestSchema handler
Implement the tool logic in the CallToolRequestSchema handler
Format the response as readable text (not raw JSON)

Check that claude_desktop_config.json is valid JSON
Verify the path to server.ts is absolute and correct
Restart Claude Desktop completely (Quit, not just close the window)
Check Claude Desktop logs (Help → View Logs)

Security

API Keys: Never commit API keys to version control. Use environment variables.
Rate Limits: The MCP server respects Rhumby API rate limits. Excessive requests may be throttled.
Access Control: MCP tools use the same permissions as your API key. If your key has read-only access, you won't be able to register boats or modify data.

MCP Server

On this page

MCP Server

On this page