OpenAI Realtime API Voice Agent

\n\n

\n\n \n \n",[18,68],"pulls","branches","forks","envVars",{"_178":40,"_180":26},"connections",{"_178":26,"_179":26},"count","unfilledCount","emptyCount",{"_33":159,"_13":18,"_66":74,"_43":-5,"_35":36,"_160":40,"_161":24,"_37":268,"_39":26,"_69":75,"_163":-5,"_70":30,"_164":-5,"_198":269,"_17":270},{"_33":167,"_13":68,"_66":67,"_43":74,"_35":36,"_160":40,"_161":24,"_37":265,"_39":26,"_69":21,"_163":169,"_70":30,"_164":-5,"_198":266,"_17":267},{"_33":261,"_13":232,"_66":225,"_43":-5,"_35":36,"_160":40,"_161":24,"_37":262,"_39":26,"_69":75,"_163":-5,"_70":30,"_164":-5,"_198":263,"_17":264},{"_33":254,"_13":255,"_66":256,"_43":225,"_35":36,"_160":40,"_161":24,"_37":257,"_39":26,"_69":228,"_163":258,"_70":30,"_164":-5,"_198":259,"_17":260},{"_33":247,"_13":248,"_66":249,"_43":225,"_35":36,"_160":40,"_161":24,"_37":250,"_39":26,"_69":228,"_163":251,"_70":30,"_164":-5,"_198":252,"_17":253},{"_33":240,"_13":241,"_66":242,"_43":225,"_35":36,"_160":40,"_161":24,"_37":243,"_39":26,"_69":228,"_163":244,"_70":30,"_164":-5,"_198":245,"_17":246},{"_33":233,"_13":234,"_66":235,"_43":225,"_35":36,"_160":40,"_161":24,"_37":236,"_39":26,"_69":228,"_163":237,"_70":30,"_164":-5,"_198":238,"_17":239},{"_33":222,"_13":223,"_66":224,"_43":225,"_35":36,"_160":110,"_161":24,"_37":226,"_39":227,"_69":228,"_163":229,"_70":30,"_164":-5,"_198":230,"_17":231},{"_33":215,"_13":216,"_66":217,"_43":-5,"_35":36,"_160":40,"_161":24,"_37":218,"_39":26,"_69":21,"_163":219,"_70":30,"_164":-5,"_198":220,"_17":221},{"_33":208,"_13":209,"_66":210,"_43":-5,"_35":36,"_160":40,"_161":24,"_37":211,"_39":26,"_69":21,"_163":212,"_70":30,"_164":-5,"_198":213,"_17":214},{"_33":201,"_13":202,"_66":203,"_43":-5,"_35":36,"_160":40,"_161":24,"_37":204,"_39":26,"_69":21,"_163":205,"_70":30,"_164":-5,"_198":206,"_17":207},{"_33":193,"_13":194,"_66":86,"_43":-5,"_35":36,"_160":40,"_161":24,"_37":195,"_39":26,"_69":196,"_163":197,"_70":30,"_164":-5,"_198":199,"_17":200},"2fe1a35e-a230-11f0-bdde-0224a6c84d84","main.tsx",["D",1759698829309],"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",[],[194],"2fe1a250-a230-11f0-bdde-0224a6c84d84","deno.json","0199b639-4047-7707-90b5-1856875494de",["D",1759698829309],"{\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}",[],[202],"2fe19ecc-a230-11f0-bdde-0224a6c84d84","README.md","0199b639-4047-7707-90b5-14c5c901dd1c",["D",1759698829309],"# 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```",[],[209],"2fe19dbe-a230-11f0-bdde-0224a6c84d84",".vtignore","0199b639-4047-7707-90b5-119f6dcf5284",["D",1759698829309],".git\n.vscode\n.cursorrules\n.DS_Store\nnode_modules\nvendor",[],[216],"f3c35d26-a230-11f0-b15a-0224a6c84d84","utils.ts","0199b639-4047-7707-90b5-0a77ea53a30b","0199b639-4047-7707-90b5-0f5da4d0f1a8",["D",1759699158018],10,"script","const MODEL = \"gpt-realtime\";\nconst INSTRUCTIONS = `\n In english, tell me the response of sending the name yana to the getFavoriteFood function\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}",[],[232,223],"routes","2fe19620-a230-11f0-bdde-0224a6c84d84","sip.ts","0199b639-4047-7707-90b5-043289ebc283",["D",1759698829309],"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;",[],[232,234],"2fe19472-a230-11f0-bdde-0224a6c84d84","rtc.ts","0199b639-4047-7707-90b5-00af64b59940",["D",1759698829309],"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;",[],[232,241],"2fe19292-a230-11f0-bdde-0224a6c84d84","observer.ts","0199b639-4047-7707-90b4-ff4cc1a5ad2c",["D",1759698829309],"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;",[],[232,248],"2fe1904e-a230-11f0-bdde-0224a6c84d84","mcp.ts","0199b639-4047-7707-90b4-facc63a14594",["D",1759698829309],"import { Hono } from \"npm:hono\";\nimport { StreamableHTTPTransport } from \"npm:@hono/mcp\";\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// MCP entrypoint over HTTP.\nmcp.all(\"/\", async (c) => {\n const transport = new StreamableHTTPTransport();\n await server.connect(transport);\n return transport.handleRequest(c);\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) {\n return makeErrorResponse(e.message);\n }\n}\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\nexport default mcp;",[],[232,255],"2fe19bf2-a230-11f0-bdde-0224a6c84d84",["D",1759698829309],[184,185,186,187,188],[232],["D",1759698829309],[],[18,68],["D",1759698829309],[182],[18],["D",1759698829309],{"_11":12,"_125":73},{"_11":12,"_121":-5,"_72":73,"_31":71,"_122":123,"_124":30},{"_39":110,"_13":16,"_33":36,"_111":77,"_112":63,"_113":64,"_114":81,"_115":116,"_117":118,"_119":14,"_120":12},"ctx",{"_52":-5,"_146":308,"_309":310,"_311":312,"_313":30,"_314":30,"_315":30,"_316":24,"_317":-5,"_318":-7,"_319":-7,"_320":26,"_321":30,"_322":30,"_323":-5,"_324":30,"_325":30,"_326":30,"_327":-5},"ENV",{"_279":280,"_281":282,"_283":16,"_284":285,"_286":287,"_288":289,"_290":291,"_292":293,"_294":295,"_296":297,"_298":299,"_300":301,"_302":303,"_304":305,"_306":307},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","fdb67791413f4386b4dbf18f354029a617f6160f","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