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 skiplimit(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
- Clone or create the project directory:
mkdir mcp-kynhood-events
cd mcp-kynhood-events
- Install dependencies:
npm install
- Configure environment (optional):
cp .env.example .env
Edit .env if you need to customize settings:
API_BASE_URL=https://***.****.com/api
DEFAULT_SKIP=0
DEFAULT_LIMIT=10
DEBUG=false
Running the Server
Development Mode
npm start
Build TypeScript
npm run build
Watch Mode (Auto-restart)
npm run dev
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
{
"mcpServers": {
"kynhood-events": {
"command": "node",
"args": [
"G:\\projects\\mcp\\event\\dist\\index.js"
],
"env": {
"API_BASE_URL": "https://***.****.com/api"
}
}
}
}
Alternative: Using TypeScript directly (no build required):
{
"mcpServers": {
"kynhood-events": {
"command": "npx",
"args": [
"-y",
"tsx",
"G:\\projects\\mcp\\event\\src\\index.ts"
],
"env": {
"API_BASE_URL": "https://***.****.com/api"
}
}
}
}
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:
Show me the latest events from Kynhood
Get specific event details:
Get details for event 68cd87381ea5
List with pagination:
Show me events 10-20 from Kynhood (skip 10, limit 10)
Multiple operations:
List the first 5 events, then show me details for the first one
Architecture
Project Structure
mcp-kynhood-events/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── api/
│ │ ├── token.ts # Token fetching logic
│ │ └── events.ts # Events API calls
│ ├── tools/
│ │ ├── listEvents.ts # List events tool
│ │ └── getEventById.ts # Get event by ID tool
│ └── utils/
│ ├── http.ts # HTTP client with retry logic
│ ├── logger.ts # Logging utility
│ └── tokenCache.ts # In-memory token cache
├── package.json
├── tsconfig.json
└── README.md
Token Management Flow
- First Request: Server checks token cache (empty)
- Fetch Token: Calls
GET /api/tokento get guest token - Cache Token: Stores token with 55-minute TTL
- Use Token: Attaches to all subsequent API requests
- 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
GET https://***.****.com/api/token
Returns JWT token for guest authentication.
2. List Events
POST https://***.****.com/api/events?skip=0&limit=10
Authorization: Bearer <token>
Body: {}
Returns paginated list of events.
3. Get Event by ID
GET https://***.****.com/api/events/:eventId
Authorization: Bearer <token>
Returns detailed event information.
Development
Adding New Tools
- Create tool file in
src/tools/ - Define input/output interfaces
- Implement tool function
- Export tool definition
- Register in
src/index.ts
Debugging
Enable debug logging:
DEBUG=true
Logs are output to stderr (visible in Claude Desktop logs).
Troubleshooting
Server Not Appearing in Claude Desktop
- Check configuration file path is correct
- Verify JSON syntax in
claude_desktop_config.json - Ensure file paths use absolute paths
- 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
# Clean and reinstall
rm -rf node_modules dist
npm install
npm run build
Testing the API Manually
You can test the Kynhood API endpoints directly:
# Get token
curl https://***.****.com/api/token
# List events (replace TOKEN with actual token)
curl -X POST "https://***.****.com/api/events?skip=0&limit=10" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d "{}"
# Get event by ID
curl "https://***.****.com/api/events/68cd8a9496a5" \
-H "Authorization: Bearer TOKEN"
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