ElevenLabs MCP Backend

# ElevenLabs MCP Backend Production-grade backend service that connects ElevenLabs Agents to Supabase using MCP (Model Context Protocol). Enables voice agents to look up real-time order details via the `lookup_order` tool. ## Features - ✅ **MCP Server (Streamable HTTP)** - Full JSON-RPC 2.0 implementation - ✅ **Supabase Integration** - Real-time order data queries - ✅ **Bearer Token Authentication** - Secure API access - ✅ **Health Check Endpoint** - Service monitoring - ✅ **REST Backup Endpoint** - Alternative to MCP for testing - ✅ **Structured Logging** - Request tracking and error handling - ✅ **Production Ready** - Works on Replit, Railway, Render, Fly, Vercel ## Architecture ``` ElevenLabs Agent → MCP Server (/mcp) → Supabase → Orders Table ``` The MCP server implements the following JSON-RPC 2.0 methods: - `initialize` - Protocol handshake - `ping` - Health check - `tools/list` - List available tools - `tools/call` - Execute tools (lookup_order) ## Quick Start ### Prerequisites - Node.js 18+ - Supabase account and project - ElevenLabs account with Agents feature ### 1. Clone and Install ```bash git clone <your-repo> cd elevenlabs-mcp-backend npm install ``` ### 2. Set Up Supabase 1. Go to your Supabase project dashboard 2. Open the SQL Editor 3. Run the SQL from `sql/schema.sql` to create the `orders` table and seed data ### 3. Configure Environment Variables Copy `env.example` to `.env`: ```bash cp env.example .env ``` Edit `.env` with your values: ```env PORT=3000 MCP_SECRET=your-secure-random-string-here SUPABASE_URL=https://your-project.supabase.co SUPABASE_SERVICE_ROLE_KEY=your-service-role-key ``` **Generate a secure MCP_SECRET:** ```bash openssl rand -hex 32 ``` **Get Supabase credentials:** - `SUPABASE_URL`: Found in Project Settings → API → Project URL - `SUPABASE_SERVICE_ROLE_KEY`: Found in Project Settings → API → service_role key (⚠️ Keep secret!) ### 4. Build and Run **Development:** ```bash npm run dev ``` **Production:** ```bash npm run build npm start ``` The server will start on `http://localhost:3000` (or your `PORT` env var). ## Testing ### Health Check ```bash curl http://localhost:3000/health ``` Expected response: ```json { "ok": true, "service": "elevenlabs-mcp-backend", "timestamp": "2025-12-23T12:00:00.000Z" } ``` ### MCP: tools/list ```bash curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your-secure-random-string-here" \ -d '{ "jsonrpc": "2.0", "id": "1", "method": "tools/list", "params": {} }' ``` Expected response: ```json { "jsonrpc": "2.0", "id": "1", "result": { "tools": [ { "name": "lookup_order", "description": "Looks up order details by order ID...", "inputSchema": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The order ID to look up (e.g., 'TR-10001')" } }, "required": ["order_id"] } } ] } } ``` ### MCP: tools/call (Existing Order) ```bash curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your-secure-random-string-here" \ -d '{ "jsonrpc": "2.0", "id": "2", "method": "tools/call", "params": { "name": "lookup_order", "arguments": { "order_id": "TR-10001" } } }' ``` Expected response: ```json { "jsonrpc": "2.0", "id": "2", "result": { "content": [ { "type": "text", "text": "Order TR-10001 is SHIPPED. ETA: December 28, 2025. Tracking: 123456789 (Yurtiçi Kargo). Last updated: December 23, 2025, 10:30 AM." } ], "structured": { "order_id": "TR-10001", "status": "SHIPPED", "eta": "2025-12-28", "carrier": "Yurtiçi Kargo", "tracking_number": "123456789", "last_update": "2025-12-23T10:30:00Z" } } } ``` ### MCP: tools/call (Missing Order) ```bash curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your-secure-random-string-here" \ -d '{ "jsonrpc": "2.0", "id": "3", "method": "tools/call", "params": { "name": "lookup_order", "arguments": { "order_id": "TR-99999" } } }' ``` Expected response: ```json { "jsonrpc": "2.0", "id": "3", "error": { "code": -32004, "message": "Order not found: TR-99999" } } ``` ### REST Backup Endpoint ```bash curl -X POST http://localhost:3000/lookup-order \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your-secure-random-string-here" \ -d '{ "order_id": "TR-10001" }' ``` Expected response: ```json { "order_id": "TR-10001", "status": "SHIPPED", "eta": "2025-12-28", "carrier": "Yurtiçi Kargo", "tracking_number": "123456789", "last_update": "2025-12-23T10:30:00Z", "issue_flag": null, "notes": "Out for delivery", "formatted_text": "Order TR-10001 is SHIPPED. ETA: December 28, 2025. Tracking: 123456789 (Yurtiçi Kargo). Last updated: December 23, 2025, 10:30 AM." } ``` ## ElevenLabs Configuration ### Setting Up MCP Server in ElevenLabs 1. **Deploy your backend** to a public URL (e.g., `https://your-app.railway.app` or `https://your-app.vercel.app`) 2. **In ElevenLabs Dashboard:** - Go to **Agents** → Select your agent → **Tools** → **MCP Servers** - Click **Add MCP Server** 3. **Configure the MCP Server:** - **MCP Server URL**: `https://your-domain.com/mcp` - **Header**: `Authorization: Bearer <your-MCP_SECRET>` - **Tool Approval Mode**: - **Always Ask** (recommended for production) - **No Approval** (for testing/demo) 4. **Test Connection:** - Click **Test Connection** in ElevenLabs - Should see: ✅ Connection successful - The `lookup_order` tool should appear in available tools ### Important Security Notes ⚠️ **Only agents with this MCP server attached can use the tool.** - Not "all agents can read the DB" - Only agents that have this MCP server connected and permission - Each agent must have the MCP server configured individually ### Agent System Prompt Fix If your agent prompt currently says: > "You have access only to uploaded TXT order records" **Replace it with:** > "You have access to real-time order records using the lookup_order tool. When a user asks about an order, always call the lookup_order tool with the order_id. Never guess order details - always use the tool to retrieve accurate information." **Keep these guardrails:** - Never guess order details - Always call the `lookup_order` tool when asked about orders - If the tool returns "Order not found", inform the user clearly ## Deployment ### Railway 1. Connect your GitHub repo to Railway 2. Railway auto-detects Node.js 3. Add environment variables in Railway dashboard: - `PORT` (auto-set by Railway, but can override) - `MCP_SECRET` - `SUPABASE_URL` - `SUPABASE_SERVICE_ROLE_KEY` 4. Deploy! ### Render 1. Create new **Web Service** 2. Connect your repo 3. Build command: `npm install && npm run build` 4. Start command: `npm start` 5. Add environment variables 6. Deploy! ### Vercel 1. Install Vercel CLI: `npm i -g vercel` 2. Run `vercel` in project directory 3. Add environment variables in Vercel dashboard 4. **Note**: Vercel serverless may have cold starts. Consider Railway/Render for better MCP performance. ### Fly.io 1. Install Fly CLI 2. Run `fly launch` 3. Add secrets: `fly secrets set MCP_SECRET=... SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=...` 4. Deploy: `fly deploy` ### Replit 1. Import your GitHub repo 2. Add environment variables in Secrets tab 3. Run `npm install && npm run build && npm start` 4. Replit auto-exposes the port ## API Reference ### Endpoints #### `GET /health` Health check (no auth required) **Response:** ```json { "ok": true, "service": "elevenlabs-mcp-backend", "timestamp": "2025-12-23T12:00:00.000Z" } ``` #### `POST /mcp` MCP JSON-RPC 2.0 endpoint (requires Bearer token) **Headers:** - `Authorization: Bearer <MCP_SECRET>` - `Content-Type: application/json` **Request Body:** JSON-RPC 2.0 format ```json { "jsonrpc": "2.0", "id": "1", "method": "tools/call", "params": { ... } } ``` **Response:** JSON-RPC 2.0 format #### `POST /lookup-order` REST backup endpoint (requires Bearer token) **Headers:** - `Authorization: Bearer <MCP_SECRET>` - `Content-Type: application/json` **Request Body:** ```json { "order_id": "TR-10001" } ``` **Response:** ```json { "order_id": "TR-10001", "status": "SHIPPED", "eta": "2025-12-28", "carrier": "Yurtiçi Kargo", "tracking_number": "123456789", "last_update": "2025-12-23T10:30:00Z", "issue_flag": null, "notes": "Out for delivery", "formatted_text": "..." } ``` ### Error Codes JSON-RPC 2.0 error codes: - `-32700`: Parse error - `-32600`: Invalid request - `-32601`: Method not found - `-32602`: Invalid params - `-32603`: Internal error - `-32004`: Order not found (custom) ## Database Schema The `orders` table has the following structure: ```sql CREATE TABLE orders ( id UUID PRIMARY KEY, order_id TEXT UNIQUE NOT NULL, status TEXT NOT NULL, -- PROCESSING, SHIPPED, DELIVERED, CANCELED, RETURNED, ON_HOLD eta DATE, carrier TEXT, tracking_number TEXT, last_update TIMESTAMPTZ DEFAULT NOW(), issue_flag TEXT, -- e.g., "address_problem", "payment_review" notes TEXT, created_at TIMESTAMPTZ DEFAULT NOW(), updated_at TIMESTAMPTZ DEFAULT NOW() ); ``` See `sql/schema.sql` for full schema and seed data. ## Development ### Project Structure ``` . ├── src/ │ ├── server.ts # Fastify server and routes │ ├── mcp.ts # MCP JSON-RPC handler │ ├── supabase.ts # Supabase client and queries │ ├── auth.ts # Bearer token middleware │ ├── logger.ts # Structured logging │ └── types.ts # TypeScript types ├── sql/ │ └── schema.sql # Database schema and seeds ├── dist/ # Compiled JavaScript (generated) ├── package.json ├── tsconfig.json ├── env.example └── README.md ``` ### Scripts - `npm run dev` - Development with hot reload (tsx watch) - `npm run build` - Compile TypeScript to JavaScript - `npm start` - Run production server - `npm run type-check` - Type check without building ### Logging Logs include: - Request IDs for tracing - Method names (MCP methods) - Tool names - Order IDs - Errors (safely, no secrets exposed) Example log: ``` [2025-12-23T12:00:00.000Z] [INFO] Processing MCP request {"requestId":"123-abc","method":"tools/call","id":"2"} [2025-12-23T12:00:00.100Z] [INFO] Order found {"requestId":"123-abc","orderId":"TR-10001","status":"SHIPPED"} ``` ## Troubleshooting ### "Order not found" for valid orders - Check Supabase connection: Verify `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` - Check table exists: Run `sql/schema.sql` in Supabase SQL Editor - Check order_id format: Must match exactly (case-sensitive) ### MCP "Test Connection" fails in ElevenLabs - Verify server is deployed and accessible - Check `Authorization` header format: `Bearer <token>` (with space) - Verify `MCP_SECRET` matches in both places - Check server logs for authentication errors ### CORS errors - Server allows all origins by default (`origin: true`) - For production, restrict in `src/server.ts` CORS config ### Supabase connection errors - Service role key must have full access (bypasses RLS) - Verify URL format: `https://xxxxx.supabase.co` (no trailing slash) - Check network/firewall allows outbound HTTPS ## Final Checklist After deployment, verify: - ✅ Server running - ✅ `/health` works - ✅ `/mcp` `tools/list` works - ✅ `/mcp` `tools/call` works - ✅ Supabase returns rows - ✅ ElevenLabs "Test Connection" passes - ✅ Voice agent can answer "Where is my order TR-10001?" ## License MIT ## Support For issues or questions: 1. Check server logs for detailed error messages 2. Verify environment variables are set correctly 3. Test with curl commands above 4. Check Supabase dashboard for data --- **Built with:** Fastify, TypeScript, Supabase, MCP (Model Context Protocol)