HTTP Transport Guide

The MCP server supports two HTTP transport protocols for client communication: Streamable HTTP (recommended) and Legacy SSE.

Transports Overview

Streamable HTTP (Recommended)

Streamable HTTP is the recommended transport per the MCP specification (2025-03-26+). It provides a unified endpoint that handles both request/response and server-sent notifications.

Endpoints

Session Lifecycle

1. Initialize Session: POST to /mcp without session ID
2. Server Response: Returns Mcp-Session-Id header
3. Subsequent Requests: Include Mcp-Session-Id header
4. Close Session: DELETE to /mcp with session ID

Session Headers

Example: Initialize Session

curl -X POST https://mcp.us-east-1.hiyve.tech/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": { "name": "my-client", "version": "1.0.0" }
    },
    "id": 1
  }'

Response Headers:

Mcp-Session-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Example: List Tools

curl -X POST https://mcp.us-east-1.hiyve.tech/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Mcp-Session-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 2
  }'

Example: Call Tool

curl -X POST https://mcp.us-east-1.hiyve.tech/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Mcp-Session-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "natural_query",
      "arguments": { "query": "show my rooms" }
    },
    "id": 3
  }'

Example: Close Session

curl -X DELETE https://mcp.us-east-1.hiyve.tech/mcp \
  -H "Mcp-Session-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Claude Desktop Configuration

{
  "mcpServers": {
    "hiyve": {
      "url": "https://mcp.us-east-1.hiyve.tech/mcp",
      "transport": "streamable-http"
    }
  }
}

Legacy SSE Transport (Deprecated)

The legacy SSE transport uses separate endpoints for the event stream and message submission. It is maintained for backward compatibility but new implementations should use Streamable HTTP.

Endpoints

Session Flow

1. Connect: GET /mcp/sse to establish SSE stream
2. Receive Session ID: Server sends session ID via SSE event
3. Send Messages: POST to /mcp/messages?sessionId=<id>

Example: Connect SSE

curl -N https://mcp.us-east-1.hiyve.tech/mcp/sse \
  -H "Authorization: Bearer <token>"

SSE Response:

event: open
data: {"sessionId": "abc123..."}

event: message
data: {"jsonrpc": "2.0", "result": {...}}

Example: Send Message

curl -X POST "https://mcp.us-east-1.hiyve.tech/mcp/messages?sessionId=abc123..." \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Status Endpoint

Check server status and active sessions:

curl https://mcp.us-east-1.hiyve.tech/mcp/status

Response:

{
  "success": true,
  "transports": {
    "streamableHttp": {
      "activeSessions": 3,
      "sessions": ["uuid1", "uuid2", "uuid3"]
    },
    "legacySse": {
      "activeSessions": 0,
      "sessions": []
    }
  },
  "activeSessions": 3,
  "toolCount": 27,
  "mcpTokenAuthEnabled": true,
  "oauthEnabled": true,
  "authMethods": ["oauth", "mcp_token", "email"],
  "supportedTransports": ["streamable-http", "sse"]
}

JSON-RPC Protocol

All MCP communication uses JSON-RPC 2.0.

Request Format

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": { ... },
  "id": 1
}

Response Format (Success)

{
  "jsonrpc": "2.0",
  "result": { ... },
  "id": 1
}

Response Format (Error)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Error description"
  },
  "id": 1
}

Error Codes

Session Management

In-Memory Storage

Sessions are stored in memory on the server. This means:

• Sessions do not persist across server restarts
• Each server instance maintains its own sessions
• Sessions expire when the underlying connection closes

Session Timeout

Sessions remain active as long as:

• The client maintains the connection (SSE) or
• The client sends requests within the timeout window

For Streamable HTTP, sessions are cleaned up when:

• The client explicitly closes with DELETE
• The transport connection is terminated

Health & Discovery Endpoints

Health Check

curl https://mcp.us-east-1.hiyve.tech/health

{
  "status": "healthy",
  "timestamp": "2025-01-14T12:00:00.000Z",
  "services": {
    "database": "connected",
    "mcp": "ready"
  }
}

CORS Configuration

The server accepts requests from:

• *.muziemedia.com
• http://localhost:*
• Configured allowedOrigins

Allowed methods: GET, POST, OPTIONS, DELETE

Allowed headers: Content-Type, Authorization, X-API-Key, x-user-email, x-timezone

Troubleshooting

"Session not found" (404)

The session ID is invalid or the session has expired. Establish a new session by sending a request without the Mcp-Session-Id header.

"Authentication required" (401)

No valid authentication credentials provided. Include either:

• Authorization: Bearer <token> header
• x-user-email + X-API-Key headers

Connection Dropped

For SSE connections, the client should implement reconnection logic. For Streamable HTTP, simply start a new session.

Request Timeout

Large queries may take time to process. The server has a default timeout, but complex AI operations may require more time. Consider breaking complex queries into smaller parts.