OpenAI Realtime API Voice Agent

\n\n

\n\n \n \n","label",[167,67],"frontend","pulls","branches","forks","envVars",{"_175":39,"_177":26},"connections",{"_175":26,"_176":26},"count","unfilledCount","emptyCount",{"_32":268,"_13":167,"_65":159,"_42":-5,"_34":35,"_160":39,"_161":85,"_36":269,"_38":26,"_68":262,"_163":-5,"_69":24,"_165":-5,"_195":270,"_17":271},{"_32":158,"_13":67,"_65":66,"_42":159,"_34":35,"_160":39,"_161":85,"_36":265,"_38":26,"_68":21,"_163":164,"_69":24,"_165":-5,"_195":266,"_17":267},{"_32":260,"_13":229,"_65":222,"_42":-5,"_34":35,"_160":39,"_161":85,"_36":261,"_38":26,"_68":262,"_163":-5,"_69":24,"_165":-5,"_195":263,"_17":264},{"_32":251,"_13":252,"_65":253,"_42":222,"_34":35,"_160":254,"_161":85,"_36":255,"_38":256,"_68":225,"_163":257,"_69":24,"_165":-5,"_195":258,"_17":259},{"_32":244,"_13":245,"_65":246,"_42":222,"_34":35,"_160":39,"_161":85,"_36":247,"_38":26,"_68":225,"_163":248,"_69":24,"_165":-5,"_195":249,"_17":250},{"_32":237,"_13":238,"_65":239,"_42":222,"_34":35,"_160":39,"_161":85,"_36":240,"_38":26,"_68":225,"_163":241,"_69":24,"_165":-5,"_195":242,"_17":243},{"_32":230,"_13":231,"_65":232,"_42":222,"_34":35,"_160":39,"_161":85,"_36":233,"_38":26,"_68":225,"_163":234,"_69":24,"_165":-5,"_195":235,"_17":236},{"_32":219,"_13":220,"_65":221,"_42":222,"_34":35,"_160":108,"_161":85,"_36":223,"_38":224,"_68":225,"_163":226,"_69":24,"_165":-5,"_195":227,"_17":228},{"_32":212,"_13":213,"_65":214,"_42":-5,"_34":35,"_160":39,"_161":85,"_36":215,"_38":26,"_68":21,"_163":216,"_69":24,"_165":-5,"_195":217,"_17":218},{"_32":205,"_13":206,"_65":207,"_42":-5,"_34":35,"_160":39,"_161":85,"_36":208,"_38":26,"_68":21,"_163":209,"_69":24,"_165":-5,"_195":210,"_17":211},{"_32":198,"_13":199,"_65":200,"_42":-5,"_34":35,"_160":39,"_161":85,"_36":201,"_38":26,"_68":21,"_163":202,"_69":24,"_165":-5,"_195":203,"_17":204},{"_32":190,"_13":191,"_65":83,"_42":-5,"_34":35,"_160":39,"_161":85,"_36":192,"_38":26,"_68":193,"_163":194,"_69":24,"_165":-5,"_195":196,"_17":197},"a920ff04-a216-11f0-b133-0224a6c84d84","main.tsx",["D",1759687865803],"http","import { Hono } from \"npm:hono\";\nimport { parseVal, serveFile } from \"https://esm.town/v/std/utils/index.ts\";\nimport mcp from \"./routes/mcp.ts\";\nimport rtc from \"./routes/rtc.ts\";\nimport sip from \"./routes/sip.ts\";\nimport observer from \"./routes/observer.ts\";\n\nconst SOURCE_URL = parseVal(Deno.env.get(\"VALTOWN_ENTRYPOINT\")).links.self.val;\n\nconst app = new Hono();\napp.route(\"/rtc\", rtc);\napp.route(\"/sip\", sip);\napp.route(\"/observer\", observer);\napp.route(\"/mcp\", mcp);\napp.get(\"/source\", (c) => c.redirect(SOURCE_URL));\n\napp.get(\"/\", () => serveFile(\"/frontend/index.html\"));\n\nexport default app.fetch;","children",[],[191],"a920fdc4-a216-11f0-b133-0224a6c84d84","deno.json","0199b591-f620-72c8-a55e-af8b88184c2a",["D",1759687865803],"{\n \"$schema\": \"https://raw.githubusercontent.com/denoland/deno/348900b8b79f4a434cab4c74b3bc8d4d2fa8ee74/cli/schemas/config-file.v1.json\",\n \"lock\": false,\n \"compilerOptions\": {\n \"noImplicitAny\": false,\n \"strict\": false,\n \"types\": [\n \"https://www.val.town/types/valtown.d.ts\"\n ],\n \"lib\": [\n \"dom\",\n \"dom.iterable\",\n \"dom.asynciterable\",\n \"deno.ns\",\n \"deno.unstable\"\n ]\n },\n \"lint\": {\n \"files\": {\n \"include\": [\n \"deno:/https/esm.town/**/*\"\n ]\n },\n \"rules\": {\n \"exclude\": [\n \"no-explicit-any\"\n ]\n }\n },\n \"node_modules_dir\": false,\n \"experimental\": {\n \"unstable-node-globals\": true,\n \"unstable-temporal\": true,\n \"unstable-worker-options\": true,\n \"unstable-sloppy-imports\": true\n }\n}",[],[199],"a920f9aa-a216-11f0-b133-0224a6c84d84","README.md","0199b591-f620-72c8-a55e-ab8a9b39c74a",["D",1759687865803],"# hello-mcp\n\n**Hello MCP** is a remix of OpenAI's hello-realtime demo that adds Model Context Protocol (MCP) support for server-side tool execution.\n\nThis demo showcases:\n- WebRTC-based voice conversations with OpenAI's Realtime API\n- **MCP (Model Context Protocol)** for secure server-side tool execution\n- A demo `getFavoriteFood` tool to demonstrate MCP functionality\n- Toggle between standard and MCP-enabled modes\n\nIf you remix the app, you'll just need to pop in your own `OPENAI_API_KEY` (from\n[platform.openai.com](https://platform.openai.com)).\n\n## What's New: MCP Support\n\n### Model Context Protocol (MCP)\nMCP enables server-side tool execution, keeping your business logic and API keys secure on the server rather than exposing them to the client.\n\n### Demo Tool: getFavoriteFood\nTry asking questions like:\n- \"What's Thomas's favorite food?\"\n- \"What does Brian like to eat?\"\n- \"Tell me about Yana's favorite food\"\n\nThe tool knows about: Thomas, Brian, Emil, Yana, Alex, Max, Justin, and Sam.\n\n## Architecture\n\n1. **Standard WebRTC Flow**:\n - Browser connects to frontend\n - Creates WebRTC offer\n - `/rtc` endpoint handles SDP negotiation with OpenAI\n - Observer established to monitor session\n\n2. **MCP-Enhanced Flow** (when enabled):\n - Same WebRTC setup as above\n - OpenAI discovers tools via MCP protocol (`/mcp`)\n - Tools execute server-side when invoked\n - Results returned through MCP protocol\n - Client triggers response generation after tool completion\n\n## API Endpoints\n- `GET /` - serves the WebRTC-based app with MCP toggle\n- `POST /rtc` - creates a new WebRTC-based Realtime API session (with optional `?mcp=true`)\n- `POST /sip` - handles an incoming Realtime API SIP call\n- `POST /observer` - internal endpoint to establish a Realtime API websocket for session control\n- `POST /mcp` - MCP protocol endpoint for tool discovery and execution\n- `GET /mcp/tools` - Debug endpoint to list available tools\n\n## Project Structure\n```\n├── frontend/ \n│ └── index.html # HTML/JS application for WebRTC with MCP support\n├── main.tsx # Main entrypoint for the val.town app\n└── routes/\n |── mcp.ts # MCP protocol handler with getFavoriteFood tool\n |── observer.ts # Server-side session control for SIP & WebRTC\n |── rtc.ts # WebRTC session setup with MCP configuration\n |── sip.ts # SIP webhook handling and session setup\n └── utils.ts # Realtime API session configuration with MCP support\n```\n\n## How to Test MCP\n\n1. **Start the app** - Click \"Start\" and allow microphone access\n2. **Check MCP is enabled** - Ensure \"Use MCP Tools\" checkbox is checked\n3. **Ask about favorite foods** - Try \"What's Thomas's favorite food?\"\n4. **Watch the logs** - You'll see MCP events including tool discovery and execution\n5. **Try without MCP** - Uncheck the box and restart to see the difference\n\n## MCP Protocol Details\n\nThe MCP implementation follows the JSON-RPC 2.0 specification:\n\n### Initialize\n```json\n{\n \"method\": \"initialize\",\n \"params\": { \"protocolVersion\": \"2025-06-18\" }\n}\n```\n\n### Tools List\n```json\n{\n \"method\": \"tools/list\",\n \"result\": { \"tools\": [...] }\n}\n```\n\n### Tool Call\n```json\n{\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"getFavoriteFood\",\n \"arguments\": { \"name\": \"Thomas\" }\n }\n}\n```",[],[206],"a920f7a2-a216-11f0-b133-0224a6c84d84",".vtignore","0199b591-f620-72c8-a55e-a65afa4049b8",["D",1759687865803],".git\n.vscode\n.cursorrules\n.DS_Store\nnode_modules\nvendor",[],[213],"2353c486-a21d-11f0-9e20-0224a6c84d84","utils.ts","0199b591-f620-72c8-a55e-9c73531455a0","0199b591-f620-72c8-a55e-a0ac011083a7",["D",1759690647879],3,"script","const MODEL = \"gpt-realtime\";\nconst INSTRUCTIONS = `\n Greet the user in English, and tell the user Alex's favorite food from the getFavoriteFood MCP tool\n`;\n\n//const VOICE = \"cedar\"; //male tenor\n//const VOICE = \"marin\"; //female alto\n//const VOICE = \"alloy\"; //female contralto\nconst VOICE = \"ash\"; //male\tbaritone\n//const VOICE = \"ballad\";// male\ttenor\n//const VOICE = \"coral\";//female soprano\n//const VOICE = \"echo\"; //male tenor\n//const VOICE = \"fable\"; //female alto\n//const VOICE = \"onyx\";//male base\n//const VOICE = \"nova\";//female alto\n//const VOICE = \"sage\";//female soprano\n//const VOICE = \"shimmer\";//female contralto\n//const VOICE = \"verse\"; //male tenor\n\nconst OPENAI_API_KEY = Deno.env.get(\"OPENAI_API_KEY\");\nif (!OPENAI_API_KEY) {\n throw new Error(\"🔴 OpenAI API key not configured\");\n}\n\nexport function makeHeaders(contentType?: string) {\n const obj: Record = {\n Authorization: `Bearer ${OPENAI_API_KEY}`,\n };\n if (contentType) obj[\"Content-Type\"] = contentType;\n return obj;\n}\n\nexport function makeSession(mcpUrl?: string) {\n const session: any = {\n type: \"realtime\",\n model: MODEL,\n instructions: INSTRUCTIONS,\n audio: {\n input: { noise_reduction: { type: \"near_field\" } },\n output: { voice: VOICE },\n },\n };\n\n // Add MCP configuration if requested\n if (mcpUrl) {\n session.tools = [{\n type: \"mcp\",\n server_label: \"hello-mcp-demo\",\n server_url: mcpUrl,\n authorization: \"demo-token-12345\", // In production, use a secure token\n require_approval: \"never\",\n }];\n }\n\n return session;\n}",[],[229,220],"routes","a920ee6a-a216-11f0-b133-0224a6c84d84","sip.ts","0199b591-f620-72c8-a55e-9a05edd5dbf4",["D",1759687865803],"import { Hono } from \"npm:hono\";\nimport { Webhook } from \"npm:svix\";\nimport { makeHeaders, makeSession } from \"./utils.ts\";\n\nconst sip = new Hono();\n\n// POST /sip : webhook endpoint\nsip.post(\"/\", async (c) => {\n // Verify the webhook.\n const OPENAI_SIGNING_SECRET = Deno.env.get(\"OPENAI_SIGNING_SECRET\");\n if (!OPENAI_SIGNING_SECRET) {\n console.error(\"🔴 webhook secret not configured\");\n return c.text(\"Internal error\", 500);\n }\n const webhook = new Webhook(OPENAI_SIGNING_SECRET);\n const bodyStr = await c.req.text();\n let callId: string | undefined;\n try {\n const headers = Object.fromEntries(c.req.raw.headers.entries());\n const payload: any = webhook.verify(bodyStr, headers);\n callId = payload.data.call_id;\n console.log(\"✅ verified webhook:\", callId);\n } catch (error) {\n console.error(`🔴 verify failed: ${error}`);\n return c.text(\"Invalid signature\", 401);\n }\n\n // Accept the call.\n const url = `https://api.openai.com/v1/realtime/calls/${callId}/accept`;\n const headers = makeHeaders(\"application/json\");\n const body = JSON.stringify(makeSession());\n const opts = { method: \"POST\", headers, body };\n const resp = await fetch(url, opts);\n if (!resp.ok) {\n const errText = await resp.text().catch(() => \"\");\n console.error(`🔴 accept failed: ${errText}`);\n return c.text(\"Internal error\", 500);\n }\n console.log(\"✅ call accepted:\", callId);\n\n // Kick off observer in the background (fire-and-forget).\n const selfUrl = new URL(c.req.url);\n fetch(`${selfUrl.origin}/observer/${callId}`, { method: \"POST\" })\n .catch((e) => console.error(\"observer trigger failed:\", e));\n\n return c.newResponse(null);\n});\n\nexport default sip;",[],[229,231],"a920ecf8-a216-11f0-b133-0224a6c84d84","rtc.ts","0199b591-f620-72c8-a55e-968a2c2c57e8",["D",1759687865803],"import { Hono } from \"npm:hono\";\nimport { makeHeaders, makeSession } from \"./utils.ts\";\n\nconst rtc = new Hono();\n\n// POST /rtc : create a new call\nrtc.post(\"/\", async (c) => {\n // Check if MCP mode is requested via query parameter\n const useMCP = c.req.query(\"mcp\") === \"true\";\n const selfUrl = new URL(c.req.url);\n const mcpUrl = useMCP ? `${selfUrl.origin}/mcp` : undefined;\n\n // Create the call.\n const url = \"https://api.openai.com/v1/realtime/calls\";\n const headers = makeHeaders();\n const fd = new FormData();\n fd.set(\"sdp\", await c.req.text());\n fd.set(\"session\", JSON.stringify(makeSession(mcpUrl)));\n const opts = { method: \"POST\", headers, body: fd };\n const resp = await fetch(url, opts);\n if (!resp.ok) {\n const errText = await resp.text().catch(() => \"\");\n console.error(`🔴 start call failed: ${resp.status} ${errText}`);\n return c.text(\"Internal error\", 500);\n }\n\n const contentType = resp.headers.get(\"Content-Type\");\n const location = resp.headers.get(\"Location\");\n const callId = location?.split(\"/\").pop();\n console.log(\"✅ call created:\", callId);\n\n // Kick off observer in the background (fire-and-forget).\n fetch(`${selfUrl.origin}/observer/${callId}`, { method: \"POST\" })\n .catch(() => {}); // catch to not crash the process\n\n return c.newResponse(resp.body, {\n headers: { \"Content-Type\": contentType },\n });\n});\n\nexport default rtc;",[],[229,238],"a920eb90-a216-11f0-b133-0224a6c84d84","observer.ts","0199b591-f620-72c8-a55e-92d08475f5ae",["D",1759687865803],"import { Hono } from \"npm:hono\";\nimport WebSocket from \"npm:ws\";\nimport { makeHeaders } from \"./utils.ts\";\n\nconst observer = new Hono();\n\n// POST /observer/:callId : self-connect to establish a web socket\nobserver.post(\"/:callId\", async (c) => {\n const callId = c.req.param(\"callId\");\n const url = `wss://api.openai.com/v1/realtime?call_id=${callId}`;\n const ws = new WebSocket(url, { headers: makeHeaders() });\n ws.on(\"open\", () => {\n console.log(\"✅ websocket connected\");\n setTimeout(() => ws.send(JSON.stringify({ type: \"response.create\" })), 250);\n });\n ws.on(\"message\", (data /*, isBinary */) => {\n const message = JSON.parse(data);\n if (message.type !== \"response.output_audio_transcript.delta\") {\n console.log(message);\n }\n });\n ws.on(\"error\", (err: Error) => {\n console.error(`🔴 websocket failed: ${err.message}`);\n });\n\n // Respond immediately; WS continues in background\n return c.newResponse(null);\n});\n\nexport default observer;",[],[229,245],"e0b11f88-a218-11f0-8cfd-0224a6c84d84","mcp.ts","0199b591-f620-72c8-a55e-8d5778d4be71",9,["D",1759688818096],6,"import { Hono } from \"npm:hono\";\nimport { McpServer } from \"npm:@modelcontextprotocol/sdk/server/mcp.js\";\nimport { z } from \"npm:zod\";\n\nconst mcp = new Hono();\nconst server = new McpServer({ name: \"hello-mcp\", version: \"1.0.0\" });\n\n// ----- Demo tool -----\nserver.tool(\n \"getFavoriteFood\",\n \"Returns the favorite food for specific people\",\n z.object({\n name: z.string().describe(\"The person's name to look up\"),\n }),\n (x) => wrap(getFavoriteFood, x),\n);\n\nconst favoriteFoods: Record = {\n thomas: \"alsacian choucroute\",\n brian: \"trail mix\",\n emil: \"nutella\",\n yana: \"french macarons\",\n alex: \"brownies\",\n max: \"feta cheese\",\n justin: \"sushi\",\n sam: \"pizza\",\n};\n\nfunction getFavoriteFood({ name }: { name: string }) {\n const favoriteFood = favoriteFoods[name.toLowerCase()];\n if (!favoriteFood) {\n const knownFoods = Object.keys(favoriteFoods).join(\", \");\n const message =\n `I don't know ${name}'s favorite food. I know about: ${knownFoods}.`;\n throw new Error(message);\n }\n\n return { favoriteFood };\n}\n\nfunction makeJsonResponse(data: any) {\n return { content: [{ type: \"json\", data }] };\n}\n\nfunction makeErrorResponse(message: string) {\n return { content: [{ type: \"text\", text: message }], isError: true };\n}\n\nfunction wrap(fn: Function, args: any) {\n try {\n return makeJsonResponse(fn(args));\n } catch (e: any) {\n return makeErrorResponse(e.message);\n }\n}\n\n// FIX: Only accept POSTs for tool calls\nmcp.post(\"/\", async (c) => {\n const reqBody = await c.req.json();\n const resp = await server.handleRequest({\n body: JSON.stringify(reqBody),\n headers: Object.fromEntries(c.req.raw.headers.entries()),\n method: c.req.method,\n url: c.req.url,\n });\n return c.newResponse(await resp.text(), {\n status: resp.status,\n headers: resp.headers,\n });\n});\n// Optional GET diagnostic endpoint\nmcp.get(\"/\", (c) => c.text(\"MCP endpoint: POST requests only\"));\n\nexport default mcp;",[],[229,252],"a920f450-a216-11f0-b133-0224a6c84d84",["D",1759687865803],"directory",[181,182,183,184,185],[229],["D",1759687865803],[],[167,67],"a920e7c6-a216-11f0-b133-0224a6c84d84",["D",1759687865803],[179],[167],["D",1759687865803],{"_11":12,"_123":72},{"_11":12,"_119":-5,"_71":72,"_30":70,"_120":121,"_122":24},{"_38":108,"_13":16,"_32":35,"_109":74,"_110":62,"_111":63,"_112":78,"_113":114,"_115":116,"_117":14,"_118":12},"ctx",{"_51":-5,"_144":309,"_310":311,"_312":313,"_314":24,"_315":24,"_316":24,"_317":85,"_318":-5,"_319":-7,"_320":-7,"_321":26,"_322":24,"_323":24,"_324":-5,"_325":24,"_326":24,"_327":24,"_328":-5},"ENV",{"_280":281,"_282":283,"_284":16,"_285":286,"_287":288,"_289":290,"_291":292,"_293":294,"_295":296,"_297":298,"_299":300,"_301":302,"_303":304,"_305":306,"_307":308},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","811aa22498c9b0b5a47e8d778de579cdb990f332","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Realtime Agent with MCP

History · index.html