MCP Kynhood Events Server

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with the Kynhood Events API. This server provides tools for listing events and retrieving detailed event information.

Features

• Automatic Token Management: Fetches and caches guest tokens automatically

• Smart Retry Logic: Handles 401 errors by refreshing tokens

• Type-Safe: Built with TypeScript for robust error handling

• Production-Ready: Comprehensive logging and error handling

Tools Available

1. listEvents

List events from the Kynhood API with pagination support.

Parameters:

• skip (optional, default: 0): Number of events to skip

• limit (optional, default: 10): Maximum number of events to return

Returns: Array of events with metadata

2. getEventById

Get detailed information about a specific event.

Parameters:

• id (required): The event ID (24-character hex string)

Returns: Complete event details

Installation

Prerequisites

• Node.js 18+

• npm or yarn

• Claude Desktop app

Steps

1. Clone or create the project directory:

2. Install dependencies:

3. Configure environment (optional):

Edit .env if you need to customize settings:

Running the Server

Development Mode

Build TypeScript

Watch Mode (Auto-restart)

Connecting to Claude Desktop

Configuration

Add this server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Alternative: Using TypeScript directly (no build required):

Note: Update the path to match your actual installation directory.

Restart Claude Desktop

After updating the configuration, completely quit and restart Claude Desktop for changes to take effect.

Usage Examples

Once connected to Claude Desktop, you can use natural language to interact with the Kynhood Events API:

Example Queries

List trending events:

Get specific event details:

List with pagination:

Multiple operations:

Architecture

Project Structure

Token Management Flow

1. First Request: Server checks token cache (empty)

2. Fetch Token: Calls GET /api/token to get guest token

3. Cache Token: Stores token with 55-minute TTL

4. Use Token: Attaches to all subsequent API requests

5. Handle 401: If token expires, automatically fetches new token and retries

Error Handling

• Network Errors: Logged and returned to Claude with context

• 401 Unauthorized: Automatically retries once with fresh token

• Invalid Responses: Validates response structure and provides meaningful errors

• Missing Parameters: Validates required parameters before API calls

API Endpoints Used

1. Get Guest Token

Returns JWT token for guest authentication.

2. List Events

Returns paginated list of events.

3. Get Event by ID

Returns detailed event information.

Development

Adding New Tools

1. Create tool file in src/tools/

2. Define input/output interfaces

3. Implement tool function

4. Export tool definition

5. Register in src/index.ts

Debugging

Enable debug logging:

Logs are output to stderr (visible in Claude Desktop logs).

Troubleshooting

Server Not Appearing in Claude Desktop

1. Check configuration file path is correct

2. Verify JSON syntax in claude_desktop_config.json

3. Ensure file paths use absolute paths

4. Restart Claude Desktop completely

Token Errors

• Server automatically handles token refresh

• Check API_BASE_URL is correct

• Verify network connectivity to api.kynhood.com

Build Errors

Testing the API Manually

You can test the Kynhood API endpoints directly:

License

MIT

Support

For issues or questions:

• Check the logs in Claude Desktop

• Verify API connectivity: curl https://***.****.com/api/token

• Review this README for configuration steps