Evento Public Server

Local MCP server for Evento developer-facing authenticated public APIs.

It runs on your machine over stdio, authenticates every API call with your API key, and can be connected to Claude Desktop (or any MCP client that supports stdio transport).

What This Server Is

• MCP transport adapter only (stdio)
• Tool calls mapped to Evento Public API routes
• Auth injected centrally using your API key
• No database access, no Supabase, no server-side persistence in MCP layer

This follows the same architecture shape as the admin MCP pattern, with different API routes and key type.

Features

• list-events
  • Lists user events
  • Optional filters: type, limit
• get-event
  • Gets one event by ID

Requirements

• Node.js 18+
• npm
• Evento developer-facing API key
• MCP client (Claude Desktop, Cursor, etc.)

Quick Start

git clone https://github.com/andreneves/evento-public-mcp.git
cd evento-public-mcp
npm install
npm run build

Create your env file:

cp .env.example .env

Set at least:

• PUBLIC_API_KEY

Then run:

npm start

Installable Skill (SKILL.md)

This repository includes an installable Claude skill file at:

• SKILL.md

Install it locally:

mkdir -p ~/.claude/skills/evento-public-mcp
cp SKILL.md ~/.claude/skills/evento-public-mcp/SKILL.md

Canonical source and docs:

• Skill file: https://github.com/andreneves/evento-public-mcp/blob/main/SKILL.md
• Docs page: https://docs.evento.so/mcp-server/skill

Versioning and sync policy

• Source of truth is this repository's SKILL.md
• When updating skill behavior or instructions, update SKILL.md first
• Keep the docs mirror page in sync: evento-docs/ai/skill.mdx
• Bump metadata.version in SKILL.md for meaningful content changes
• Verify the docs page still reflects the full file content before release

Environment Variables

Required:

• PUBLIC_API_KEY
  • Developer-facing Evento API key used as Authorization: Bearer <key>

Optional:

• EVENTO_API_BASE_URL (default: https://evento.so/api)
• EVENTO_API_TIMEOUT_MS (default: 15000)
• EVENTO_API_RETRY_ATTEMPTS (default: 2)
• EVENTO_API_RETRY_DELAY_MS (default: 250)
• EVENTO_PUBLIC_API_KEY (legacy compatibility fallback if PUBLIC_API_KEY is missing)
• EVENTO_SMOKE_USERNAME (used by smoke command)

MCP Client Configuration

Example Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "evento-public": {
      "command": "node",
      "args": ["/absolute/path/to/evento-public-mcp/dist/index.js"],
      "env": {
        "PUBLIC_API_KEY": "your-evento-api-key",
        "EVENTO_API_BASE_URL": "https://evento.so/api"
      }
    }
  }
}

Notes:

• Use an absolute path in args
• Restart Claude Desktop after config changes

Available Tools

list-events

List events for a user.

Input:

• username (required, string)
• type (optional, upcoming | past | profile)
• limit (optional, number)

Route mapping:

• GET /public/v1/users/{username}/events

get-event

Get event details by ID.

Input:

• eventId (required, string)

Route mapping:

• GET /public/v1/events/{eventId}

Architecture

Key files:

• src/index.ts
  • process entrypoint
• src/mcp-server.ts
  • MCP protocol handling (tools/list, tools/call)
• src/public-tools.ts
  • single runtime registry (PUBLIC_TOOLS)
  • generic executor (executePublicTool)
  • auth/header injection, path interpolation, timeout/retry, normalized response
• PUBLIC_MCP.tools.json
  • manifest mirror of runtime tools

Execution flow:

1. MCP client calls tools/list
2. server returns PUBLIC_TOOLS
3. MCP client calls tools/call
4. server delegates to executePublicTool(name, args)
5. executor validates required args, resolves path placeholders, strips path args from body
6. executor calls Evento API with auth header and retry/timeout policy
7. executor normalizes success/error payload back to MCP response

Local Development

Install deps:

npm install

Run directly in TypeScript:

npm run dev

Build:

npm run build

Run built server:

npm start

Testing and Verification

Run tests:

npm test

Run build + tests:

npm run verify

Smoke check (live API):

EVENTO_SMOKE_USERNAME=your-username npm run smoke

Test layers included:

• Unit: tests/public-tools.unit.test.ts
• Manifest parity: tests/manifest-parity.test.ts
• MCP stdio e2e: tests/mcp.e2e.test.ts

Adding a New Tool

1. Add a new tool definition to PUBLIC_TOOLS in src/public-tools.ts
   • name, description, method, path, input schema
2. Ensure route/path placeholders align with args
3. Update PUBLIC_MCP.tools.json to match
4. Add/extend unit tests and parity assertions
5. Run npm run verify

Error Handling and Retry Policy

• Retries on retryable statuses: 408, 429, 5xx
• Retries on retryable network errors (timeout / DNS / connection reset classes)
• Controlled by env vars (EVENTO_API_RETRY_*)
• Returns MCP isError: true with structured error payload when failed

Troubleshooting

Missing API key

Symptom:

• Tool call returns missing key error

Fix:

• Set PUBLIC_API_KEY in MCP client env config

Tools not visible in client

Fix checklist:

1. Run npm run build
2. Confirm dist/index.js exists
3. Confirm absolute path in MCP config
4. Restart MCP client app

API errors

Fix checklist:

1. Verify key is valid for authenticated public endpoints
2. Verify EVENTO_API_BASE_URL
3. Run smoke check with a known username

Security Notes

• Keep API keys in local env config, not source control
• This project does not store your API key beyond process env

License

ISC