Skip to main content
Glama
sevenlabsxyz

Evento Public MCP Server

by sevenlabsxyz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Evento Public MCP 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.

Related MCP server: eesti.ai events MCP server

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

Available Tools

2 tools
get-eventA

Get detailed information about a specific event by its ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
eventIdYesThe ID of the event to retrieve

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden. 'Get detailed information' clearly indicates a read-only retrieval operation with no side effects, though it does not specify behavior for missing IDs or error cases. For a simple read-by-ID tool, the core behavior is sufficiently transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler. Every word contributes to the meaning, and the description is appropriately sized for a simple one-parameter retrieval tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get-by-ID tool with one fully documented required parameter, the description is nearly complete. The only minor gap is that no output schema exists and the description does not clarify what fields 'detailed information' includes, but an agent can still invoke the tool correctly with the given information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already fully documents eventId as 'The ID of the event to retrieve'. The description adds no new parameter-level meaning beyond restating that the event is retrieved by ID, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('Get'), a resource ('event'), and the selection by ID. It distinguishes from the sibling list-events by focusing on one specific event rather than a collection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when the agent already knows the event ID and needs details for that single event, while list-events would be used to enumerate events. It provides clear context but does not explicitly name the alternative or state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-eventsB

List events for a specific user. Returns upcoming, past, or all profile events.

ParametersJSON Schema
NameRequiredDescriptionDefault
typeNoFilter events by type: upcoming, past, or profile (all public events)
limitNoMaximum number of events to return
usernameYesThe username to list events for

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral disclosure burden. It only restates the return categories and does not mention pagination, default type when omitted, ordering, read-only nature, or how 'profile' events are selected.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The action and target are front-loaded, and the return categories are listed compactly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is adequate for a straightforward list operation: the core purpose is clear, and the schema covers parameters. However, missing default behavior for when type/limit are omitted, no pagination/ordering context, and no output schema leave moderate gaps for an agent selecting and invoking the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description's mention of 'upcoming, past, or all profile events' mirrors the type enum and adds no substantial meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'List events for a specific user', and enumerates the three categories returned. It is clear enough to distinguish from the sibling get-event, though it does not explicitly contrast them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to use list-events versus get-event, nor when each event type filter is appropriate. The description implies a user-scoped listing but provides no selection criteria or alternative routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.0
    • First observedget-event
    • First observedlist-events
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 2 tools

Disambiguation5/5

list-events returns a collection of events for a user, while get-event returns details for a single event by ID. The purposes are clearly distinct and unlikely to be confused.

Naming Consistency5/5

Both tools follow the same kebab-case verb-noun pattern: list-events and get-event. The naming is consistent and predictable.

Tool Count3/5

Two tools is minimal for a server, though acceptable for a narrow read-only event API. It falls below the typical well-scoped 3-15 tool range.

Completeness4/5

The core read workflow is covered: listing events and fetching event details. There are minor gaps such as no search or filter-by-date tool, but for a public read-only event server this is reasonable.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers