MCP Server Documentation

Let your AI agent book meetings, check trust scores, and manage stakes through the Model Context Protocol.

Quick Start

1. Create an API key in your dashboard. 2. Call the MCP endpoint with your key.

curl -X POST https://ghostnot.com/api/mcp/ghostnot/check_requirements \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gnk_your_key_here" \
  -d '{"input": {"host_slug": "alice-host"}}'

Auto-Discovery

MCP-compatible clients can auto-discover GhostNot's capabilities:

# Server card (no auth required)
GET https://ghostnot.com/.well-known/mcp.json

# Tool listing (no auth required)
GET https://ghostnot.com/api/mcp/tools

# Authenticated tool listing (returns user-specific data)
POST https://ghostnot.com/api/mcp/tools
  Header: X-API-Key: gnk_your_key_here

Authentication

All tool invocations require an API key passed via the X-API-Key header. Each key has:

•Permissions — granular control over which tools the key can access (book, cancel, check_requirements, view_profile, view_bookings)
•Max auto-stake — maximum amount the agent can stake per booking without user confirmation
•Activity logging — every tool call is logged with timestamp and key ID

Available Tools

ghostnot/check_requirements

Check what a host requires and whether your trust score qualifies for reduced stakes.

Permission: check_requirements

// Request
POST /api/mcp/ghostnot/check_requirements
{
  "input": {
    "host_slug": "alice-host"
  }
}

// Response
{
  "data": {
    "stake_required": 125,
    "requester_trust_score": 72,
    "requester_trust_tier": "trusted",
    "host_name": "Alice Host"
  }
}

ghostnot/create_booking

Book a meeting slot. Automatically places a stake hold if required.

Permission: book

// Request
POST /api/mcp/ghostnot/create_booking
{
  "input": {
    "host_slug": "alice-host",
    "scheduled_at": "2026-04-15T14:00:00Z",
    "duration_minutes": 30
  }
}

// Response
{
  "data": {
    "booking_id": "abc-123",
    "stake_amount": 125,
    "stake_status": "held"
  }
}

ghostnot/cancel_booking

Cancel an upcoming booking. Refund and reputation impact depend on timing.

Permission: cancel

// Request
POST /api/mcp/ghostnot/cancel_booking
{
  "input": {
    "booking_id": "abc-123"
  }
}

// Response
{
  "data": {
    "refund_status": "released",
    "reputation_impact": "No impact (early cancellation)"
  }
}

ghostnot/get_trust_profile

Retrieve the authenticated user's trust score, tier, and meeting stats.

Permission: view_profile

// Request (no input needed — uses authenticated user)
POST /api/mcp/ghostnot/get_trust_profile
{
  "input": {}
}

// Response
{
  "data": {
    "trust_score": 72,
    "trust_tier": "trusted",
    "total_meetings": 25,
    "successful_meetings": 23,
    "no_shows": 2
  }
}

ghostnot/get_booking_status

Check the status of an existing booking.

Permission: view_bookings

// Request
POST /api/mcp/ghostnot/get_booking_status
{
  "input": {
    "booking_id": "abc-123"
  }
}

// Response
{
  "data": {
    "status": "confirmed",
    "attendance_status": "pending",
    "stake_status": "held",
    "scheduled_at": "2026-04-15T14:00:00Z"
  }
}

Error Handling

All errors follow a consistent format with an error code and message:

// Error response format
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have 'book' permission"
  }
}

// Common error codes:
// 400 BAD_INPUT        — Missing or invalid parameters
// 401 UNAUTHORIZED     — Missing or invalid API key
// 403 FORBIDDEN        — Key lacks required permission
// 404 NOT_FOUND        — Host or booking not found
// 429 RATE_LIMITED     — Too many requests
// 500 INTERNAL_ERROR   — Server error (we're notified)

Rate Limits

MCP endpoints are rate-limited per API key:

Endpoint	Limit
check_requirements	60 req/min
create_booking	10 req/min
cancel_booking	10 req/min
get_trust_profile	60 req/min
get_booking_status	60 req/min

Every response includes X-Response-Time and X-Request-Id headers for debugging.