EventHive MCP Server

An MCP (Model Context Protocol) server that lets Claude autonomously set up EventHive accounts — creating events, deploying tools, and seeding starter data — through natural conversation.

Scope note: This is the EventHive setup MCP — the "configurator" companion. It is explicitly not the Erleah engine MCP (real-time event intelligence, war room, knowledge chat). Those will be separate servers.

---

What it does

Connect this server to any Claude client and say something like:

"Set up my March conference. Create the event, deploy a task tracker, and add a few starter tasks."

Claude will:

1. Call get_context to understand the account
2. Call create_event (with a dry run preview first)
3. Call deploy_tool to deploy the Event Ops Tracker
4. Call bulk_seed (dry run first, then real) to populate starter tasks

All without you touching the EventHive UI.

---

Quick start — connect Claude

1. Get an agent API key

Log in to EventHive and run:

curl -X POST https://eventhive.tools/api/agent/keys \
  -H 'content-type: application/json' \
  -b 'eventhive_session=<your-session-cookie>' \
  -d '{"label":"my-claude-key"}'

Or use Settings → API Keys in the EventHive UI (if available). The key starts with ehk_ and is shown once — save it.

2. Add the MCP server to Claude

In Claude Desktop (or any MCP-compatible client), add a custom server:

Field	Value
URL	https://eventhive.tools/mcp
Transport	Streamable HTTP (or SSE — the server supports both)
Auth header	Authorization: Bearer ehk_<your-key>

Note: Some Claude clients let you set headers directly in the server config. Others require a proxy or the eventhive-mcp sidecar to inject the header. See the client-specific instructions below.

Claude Desktop (claude_desktop_config.json)

The server uses HTTP transport, not stdio. Use a reverse-proxy approach or the MCP proxy pattern if your Claude Desktop version doesn't support remote HTTP servers directly.

For remote HTTP MCP servers (Claude.ai Pro / Teams):

• Add the server URL: https://eventhive.tools/mcp
• Set the bearer token as configured by your client

3. Start the conversation

"Set up my summer exhibition. Create the event for June 2026, 
deploy a run sheet and a budget tracker, and seed the run sheet 
with a few placeholder sessions."

---

Running locally (for development)

# 1. Clone and install
git clone https://github.com/Visual-Hive/eventhive-mcp.git
cd eventhive-mcp
npm install

# 2. Set env vars
export EVENTHIVE_BASE_URL=http://localhost:5200   # local EventHive dev server
export EVENTHIVE_AGENT_KEY=ehk_...                # key from EventHive UI
export PORT=3001

# 3. Start
npm run dev                                        # watch mode
# or: npm start                                    # compiled build

# Health check
curl http://localhost:3001/health
# → {"ok":true,"service":"eventhive-mcp","version":"1.0.0"}

Run the smoke test

export EVENTHIVE_AGENT_KEY=ehk_...
export EVENTHIVE_BASE_URL=https://eventhive.tools   # or http://localhost:5200
bash scripts/smoke.sh

The smoke test exercises all agent API endpoints in sequence: context, create event, deploy tool, import data, configure tool.

---

The 7 MCP tools

Always follow the get_context first convention — tool descriptions remind Claude of this.

Tool	Type	What it does
eventhive/v1/get_context	Read	Full account snapshot — member, events, deployed tools, record counts. Always call first.
eventhive/v1/list_tools	Read	Lists deployable tool templates (slug, name, purpose) + which are already in the account.
eventhive/v1/get_tool_data	Read	Fetch records for a (toolSlug, resource) pair, e.g. all tasks in event-ops-tracker.
eventhive/v1/create_event	Write	Create a new event. Dedup pre-check + dry_run + force override.
eventhive/v1/deploy_tool	Write	Deploy a tool template. Returns widget URL. dry_run validates config first.
eventhive/v1/configure_tool	Write	Update config on an existing instance. Config is merged. dry_run previews.
eventhive/v1/bulk_seed	Write	Import records into a tool resource. Defaults to merge. dry_run always first.

---

Safety design

dry_run on every write tool

All four write tools accept dry_run: true — returns a preview, performs no write. Claude's tool descriptions explicitly instruct it to show a dry-run preview and get confirmation before writing.

bulk_seed defaults to merge

mode: "replace" must be set explicitly. Replace is destructive (deletes all existing records for that resource before importing) — the tool description warns Claude clearly.

create_event dedup

If an event with the same name (and date, if provided) already exists, a 409 is returned with the existing event details. Claude is instructed to reuse the existing event rather than force-creating a duplicate.

Structured errors

All API errors are mapped to typed, actionable error messages — never raw HTTP status. Claude can self-correct from validation errors, not-found responses, and rate limits.

---

Deployment (production — Hetzner)

The MCP server runs as a Docker service in the same compose stack as EventHive.

Prerequisites on the production server:

# The eventhive-mcp repo must be cloned as a sibling of the eventhive repo
cd /opt
git clone git@github.com:Visual-Hive/eventhive-mcp.git

Add to .env on the server:

EVENTHIVE_AGENT_KEY=ehk_<the-key-for-the-mcp-service-account>

Deploy:

cd /opt/eventhive
docker compose -f docker-compose.production.yml up -d --build eventhive-mcp

Caddy automatically routes https://eventhive.tools/mcp → eventhive-mcp:3001 (configured in Caddyfile — flush_interval -1 ensures SSE streaming is not buffered).

The MCP service uses the internal Docker network to call http://app:3000 — agent-API traffic never leaves the Docker network.

---

Architecture

Claude client
     │
     │  HTTPS  POST /mcp  (Streamable HTTP / SSE)
     ▼
  Caddy  (eventhive.tools)
     │  /mcp* → eventhive-mcp:3001  (flush_interval -1)
     ▼
eventhive-mcp  (Node 20, port 3001)
     │  Authorization: Bearer ehk_...
     │  http://app:3000/api/agent/*   (internal Docker network)
     │  http://app:3000/api/tools/*/data/*
     ▼
EventHive app  (SvelteKit, port 3000)
     │
     ▼
PostgreSQL (eventhive DB)

---

Known tech debt

Item	Detail
Static tool catalogue	list_tools uses a hardcoded KNOWN_TEMPLATES array that mirrors the EventHive erleah-api.ts system prompt. If a /api/agent/templates endpoint is added to EventHive, replace the static list with a live fetch.
Single-account key auth	The EVENTHIVE_AGENT_KEY env var ties this server instance to one EventHive member. Multi-tenant OAuth (one key per Claude user) is the next step but requires a Claude OAuth connector and the EventHive OAuth flow.
Tool Data API import auth	The /api/tools/{slug}/data/import endpoint was extended in Sprint 48 to accept bearer auth (previously cookie-only). If that change is reverted, bulk_seed will fail with 401.
No tool-data delete endpoint for replace	bulk_seed replace mode calls individual DELETE /{resource}/{id} for each record — slow for large datasets. A bulk-delete endpoint would be cleaner.

---

Scope boundary

This server handles account setup:

• Creating events and workspaces
• Deploying and configuring tool instances
• Seeding starter data

It does not handle:

• Real-time event intelligence (Erleah / war room)
• Knowledge chat or RAG queries
• Live production control (GoLive, run-of-show)

Those capabilities belong to a separate Erleah MCP server (not yet built). The distinction: this server sets things up before the event; the Erleah MCP assists during it.