OpenAI Realtime API Voice Agent

\n\n

\n\n \n \n",[18,69],"pulls","branches","forks",2,"envVars",{"_191":41,"_193":26},"connections",{"_191":26,"_192":26},"count","unfilledCount","emptyCount",{"_34":171,"_13":18,"_67":83,"_44":-5,"_36":37,"_174":41,"_179":24,"_38":285,"_40":26,"_70":84,"_172":-5,"_71":30,"_175":-5,"_212":286,"_17":287},{"_34":178,"_13":69,"_67":68,"_44":83,"_36":37,"_174":77,"_179":24,"_38":282,"_40":41,"_70":21,"_172":181,"_71":30,"_175":-5,"_212":283,"_17":284},{"_34":278,"_13":247,"_67":241,"_44":-5,"_36":37,"_174":41,"_179":24,"_38":279,"_40":26,"_70":84,"_172":-5,"_71":30,"_175":-5,"_212":280,"_17":281},{"_34":270,"_13":271,"_67":272,"_44":241,"_36":37,"_174":273,"_179":24,"_38":274,"_40":41,"_70":243,"_172":275,"_71":30,"_175":-5,"_212":276,"_17":277},{"_34":263,"_13":264,"_67":265,"_44":241,"_36":37,"_174":41,"_179":24,"_38":266,"_40":26,"_70":243,"_172":267,"_71":30,"_175":-5,"_212":268,"_17":269},{"_34":255,"_13":256,"_67":257,"_44":241,"_36":37,"_174":258,"_179":24,"_38":259,"_40":233,"_70":243,"_172":260,"_71":30,"_175":-5,"_212":261,"_17":262},{"_34":248,"_13":249,"_67":250,"_44":241,"_36":37,"_174":41,"_179":24,"_38":251,"_40":26,"_70":243,"_172":252,"_71":30,"_175":-5,"_212":253,"_17":254},{"_34":238,"_13":239,"_67":240,"_44":241,"_36":37,"_174":119,"_179":24,"_38":242,"_40":208,"_70":243,"_172":244,"_71":30,"_175":-5,"_212":245,"_17":246},{"_34":230,"_13":231,"_67":232,"_44":-5,"_36":37,"_174":233,"_179":24,"_38":234,"_40":26,"_70":21,"_172":235,"_71":30,"_175":-5,"_212":236,"_17":237},{"_34":222,"_13":223,"_67":224,"_44":-5,"_36":37,"_174":225,"_179":24,"_38":226,"_40":77,"_70":21,"_172":227,"_71":30,"_175":-5,"_212":228,"_17":229},{"_34":215,"_13":216,"_67":217,"_44":-5,"_36":37,"_174":186,"_179":24,"_38":218,"_40":26,"_70":21,"_172":219,"_71":30,"_175":-5,"_212":220,"_17":221},{"_34":206,"_13":207,"_67":95,"_44":-5,"_36":37,"_174":208,"_179":24,"_38":209,"_40":41,"_70":210,"_172":211,"_71":30,"_175":-5,"_212":213,"_17":214},"39d77a08-87f2-11f0-8c99-0224a6c84d84","main.tsx",9,["D",1756813486382],"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",[],[207],"396e1a5e-87f2-11f0-98c7-0224a6c84d84","deno.json","396e1afe-87f2-11f0-98c7-0224a6c84d84",["D",1756813486377],"{\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}",[],[216],"6f3f92c0-87f7-11f0-8245-0224a6c84d84","README.md","01990a31-913b-7345-a24a-ef358561a0b2",15,["D",1756815724072],"# 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```",[],[223],"3971d5ae-87f2-11f0-b5ac-0224a6c84d84",".vtignore","3971d6f8-87f2-11f0-b5ac-0224a6c84d84",3,["D",1756813486401],".git\n.vscode\n.cursorrules\n.DS_Store\nnode_modules\nvendor",[],[231],"d33d8092-8aaf-11f0-9391-0224a6c84d84","utils.ts","01990a31-913b-7345-a24a-e588c8e5287c","01990a31-913b-7345-a24a-e8c1bf3b5dc2",["D",1757114821629],"script","const MODEL = \"gpt-realtime\";\nconst INSTRUCTIONS = `\n Greet the user in English, and thank them for trying the new OpenAI Realtime API.\n Give them a brief summary based on the list below, and then ask if they have any questions.\n Answer questions using the information below. For questions outside this scope,\n apologize and say you can't help with that.\n ---\n Short summary:\n - The Realtime API is now generally available, and has improved instruction following, voice naturalness, and audio quality.\n There are two new voices and it's easier to develop for. There's also a new telephony integration for phone scenarios.\n Full list of improvements:\n - generally available (no longer in beta)\n - two new voices (Cedar and Marin)\n - improved instruction following\n - enhanced voice naturalness\n - higher audio quality\n - improved handling of alphanumerics (eg, properly understanding credit card and phone numbers)\n - support for the OpenAI Prompts API\n - support for MCP-based tools\n - auto-truncation to reduce context size\n - native telephony support, making it simple to connect voice calls to existing Realtime API applications\n - when using WebRTC, you can connect without needing an ephemeral token\n - when using WebRTC, you can now control sessions (including tool calls) from the server\n - when using WebRTC, you can now send video to the model, and it can respond based on what it sees\n - many helpful bugfixes!\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(useMCP?: boolean, 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 (useMCP && 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}",[],[247,239],"routes","43bc6e18-87f0-11f0-ba02-0224a6c84d84","sip.ts","01990a31-913b-7345-a24a-e34aa31ad6da",["D",1756812644593],"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;",[],[247,249],"6f3897d6-87f7-11f0-9f04-0224a6c84d84","rtc.ts","01990a31-913b-7345-a24a-deedb45ded9b",14,["D",1756815724071],"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(useMCP, 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;",[],[247,256],"43bc638c-87f0-11f0-ba02-0224a6c84d84","observer.ts","01990a31-913b-7345-a24a-da6bc15ddc7e",["D",1756812644593],"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.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;",[],[247,264],"6f332422-87f7-11f0-89f5-0224a6c84d84","mcp.ts","399f9e08-87f2-11f0-bf71-0224a6c84d84",13,["D",1756815724070],"import { Hono } from \"npm:hono\";\n\nconst mcp = new Hono();\n\n// Demo tool: getFavoriteFood with some test data\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\n// MCP Tools definition\nconst tools = [\n {\n name: \"getFavoriteFood\",\n description: \"Returns the favorite food for specific people\",\n inputSchema: {\n type: \"object\",\n properties: {\n name: {\n type: \"string\",\n description: \"The person's name to look up\"\n }\n },\n required: [\"name\"]\n }\n }\n];\n\n// Handle MCP JSON-RPC requests\nmcp.post(\"/\", async (c) => {\n const body = await c.req.json();\n \n console.log(\"MCP Request:\", body);\n\n // Handle initialize method\n if (body.method === \"initialize\") {\n const clientVersion = body.params?.protocolVersion || \"2025-06-18\";\n return c.json({\n jsonrpc: \"2.0\",\n id: body.id,\n result: {\n protocolVersion: clientVersion,\n capabilities: {\n tools: {\n listChanged: true // Critical: tells OpenAI to fetch tools\n }\n },\n serverInfo: {\n name: \"hello-mcp\",\n version: \"1.0.0\"\n }\n }\n });\n }\n\n // Handle tools/list method\n if (body.method === \"tools/list\") {\n return c.json({\n jsonrpc: \"2.0\",\n id: body.id,\n result: {\n tools: tools\n }\n });\n }\n\n // Handle tools/call method\n if (body.method === \"tools/call\") {\n const { name, arguments: args } = body.params || {};\n \n if (name === \"getFavoriteFood\") {\n const personName = args?.name?.toLowerCase() || \"\";\n const favoriteFood = favoriteFoods[personName];\n \n const result = favoriteFood \n ? {\n success: true,\n data: {\n person: args.name,\n favoriteFood: favoriteFood\n }\n }\n : {\n success: false,\n error: `I don't know ${args.name}'s favorite food. I know about: ${Object.keys(favoriteFoods).join(\", \")}`\n };\n \n return c.json({\n jsonrpc: \"2.0\",\n id: body.id,\n result: {\n content: [\n {\n type: \"text\",\n text: JSON.stringify(result)\n }\n ]\n }\n });\n }\n \n // Tool not found\n return c.json({\n jsonrpc: \"2.0\",\n id: body.id,\n error: {\n code: -32601,\n message: `Tool not found: ${name}`\n }\n });\n }\n\n // Handle unknown notifications (like notifications/initialized)\n if (body.method?.startsWith(\"notifications/\")) {\n return c.json({\n jsonrpc: \"2.0\",\n id: body.id,\n result: {}\n });\n }\n\n // Unknown method\n return c.json({\n jsonrpc: \"2.0\",\n id: body.id,\n error: {\n code: -32601,\n message: `Method not found: ${body.method}`\n }\n });\n});\n\n// Debug endpoint to list tools\nmcp.get(\"/tools\", async (c) => {\n return c.json({\n tools: tools\n });\n});\n\nexport default mcp;",[],[247,271],"43bc72a0-87f0-11f0-ba02-0224a6c84d84",["D",1756812644593],[197,198,199,200,201],[247],["D",1756813486419],[],[18,69],["D",1756812644593],[195],[18],["D",1756812644593],{"_11":12,"_135":74},{"_11":12,"_131":-5,"_73":74,"_31":72,"_132":133,"_134":30},{"_40":119,"_13":16,"_34":37,"_120":86,"_121":64,"_122":123,"_124":90,"_125":126,"_127":128,"_129":14,"_130":12},"ctx",{"_53":-5,"_156":325,"_326":327,"_328":329,"_330":30,"_331":30,"_332":30,"_333":24,"_334":-5,"_335":-7,"_336":-7,"_337":26,"_338":30,"_339":30,"_340":-5,"_341":30,"_342":30,"_343":30,"_344":-5},"ENV",{"_296":297,"_298":299,"_300":16,"_301":302,"_303":304,"_305":306,"_307":308,"_309":310,"_311":312,"_313":314,"_315":316,"_317":318,"_319":320,"_321":322,"_323":324},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","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 · frontend