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":269,"_13":167,"_65":159,"_42":-5,"_34":35,"_160":39,"_161":85,"_36":270,"_38":26,"_68":263,"_163":-5,"_69":24,"_165":-5,"_195":271,"_17":272},{"_32":158,"_13":67,"_65":66,"_42":159,"_34":35,"_160":39,"_161":85,"_36":266,"_38":26,"_68":21,"_163":164,"_69":24,"_165":-5,"_195":267,"_17":268},{"_32":261,"_13":230,"_65":223,"_42":-5,"_34":35,"_160":39,"_161":85,"_36":262,"_38":26,"_68":263,"_163":-5,"_69":24,"_165":-5,"_195":264,"_17":265},{"_32":253,"_13":254,"_65":255,"_42":223,"_34":35,"_160":108,"_161":85,"_36":256,"_38":257,"_68":226,"_163":258,"_69":24,"_165":-5,"_195":259,"_17":260},{"_32":245,"_13":246,"_65":247,"_42":223,"_34":35,"_160":108,"_161":85,"_36":248,"_38":249,"_68":226,"_163":250,"_69":24,"_165":-5,"_195":251,"_17":252},{"_32":238,"_13":239,"_65":240,"_42":223,"_34":35,"_160":39,"_161":85,"_36":241,"_38":26,"_68":226,"_163":242,"_69":24,"_165":-5,"_195":243,"_17":244},{"_32":231,"_13":232,"_65":233,"_42":223,"_34":35,"_160":39,"_161":85,"_36":234,"_38":26,"_68":226,"_163":235,"_69":24,"_165":-5,"_195":236,"_17":237},{"_32":220,"_13":221,"_65":222,"_42":223,"_34":35,"_160":108,"_161":85,"_36":224,"_38":225,"_68":226,"_163":227,"_69":24,"_165":-5,"_195":228,"_17":229},{"_32":213,"_13":214,"_65":215,"_42":-5,"_34":35,"_160":39,"_161":85,"_36":216,"_38":26,"_68":21,"_163":217,"_69":24,"_165":-5,"_195":218,"_17":219},{"_32":205,"_13":206,"_65":207,"_42":-5,"_34":35,"_160":208,"_161":85,"_36":209,"_38":39,"_68":21,"_163":210,"_69":24,"_165":-5,"_195":211,"_17":212},{"_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},"06ac2cf2-9fce-11f0-b51b-0224a6c84d84","main.tsx",["D",1759436767161],"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],"06ac2b4e-9fce-11f0-b51b-0224a6c84d84","deno.json","0199a69a-800d-76c4-a76a-40c301cd0ce2",["D",1759436767161],"{\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],"47faadc0-a215-11f0-8823-0224a6c84d84","README.md","0199a69a-800d-76c4-a76a-3e175d951709",7,["D",1759687273396],"# 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],"06ac25fe-9fce-11f0-b51b-0224a6c84d84",".vtignore","0199a69a-800d-76c4-a76a-3817211ffd66",["D",1759436767161],".git\n.vscode\n.cursorrules\n.DS_Store\nnode_modules\nvendor",[],[214],"2900df52-a22e-11f0-95ab-0224a6c84d84","utils.ts","0199a69a-800d-76c4-a76a-3107deafae5d","0199a69a-800d-76c4-a76a-364ec52a8b81",["D",1759697958849],30,"script","const MODEL = \"gpt-realtime\";\nconst INSTRUCTIONS = `\n Tell me the top 3 hacker news stories in the last 2 hours using the getRecentTopStories 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}",[],[230,221],"routes","06ac1c76-9fce-11f0-b51b-0224a6c84d84","sip.ts","0199a69a-800d-76c4-a76a-2f2a066a5d4b",["D",1759436767161],"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;",[],[230,232],"06ac1b40-9fce-11f0-b51b-0224a6c84d84","rtc.ts","0199a69a-800d-76c4-a76a-299e95a0e04a",["D",1759436767161],"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;",[],[230,239],"2900db9c-a22e-11f0-95ab-0224a6c84d84","observer.ts","0199a69a-800d-76c4-a76a-26ae019037e2",["D",1759697958849],14,"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;",[],[230,246],"2900cbc0-a22e-11f0-95ab-0224a6c84d84","mcp.ts","0199a69a-800d-76c4-a76a-23ea07f65a22",["D",1759697958849],59,"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 body = await c.req.json().catch(() => null);\n console.log(\"MCP endpoint hit! Incoming JSON:\", body);\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 -----\n// server.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\n// const 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// function 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 unixNow() {\n return Math.floor(Date.now() / 1000);\n}\n\nasync function getRecentTopStories(\n { hours = 24, limit = 5 }: { hours?: number; limit?: number },\n) {\n const seconds = (hours || 24) * 60 * 60;\n const cutoff = unixNow() - seconds;\n const ids = await fetch(\n \"https://hacker-news.firebaseio.com/v0/topstories.json\",\n ).then((r) => r.json());\n const stories: any[] = [];\n for (const id of ids) {\n if (stories.length >= Math.max(1, Math.min(limit || 5, 20))) break;\n const item = await fetch(\n `https://hacker-news.firebaseio.com/v0/item/${id}.json`,\n ).then((r) => r.json());\n if (item && item.time >= cutoff) {\n stories.push({\n id: item.id,\n title: item.title,\n url: item.url,\n score: item.score,\n by: item.by,\n time: item.time,\n hnLink: `https://news.ycombinator.com/item?id=${item.id}`,\n });\n }\n }\n return { stories };\n}\n\nserver.tool(\n \"getRecentTopStories\",\n \"Returns the top Hacker News stories from the last X hours.\",\n z.object({\n hours: z.number()\n .min(1).max(720).default(24)\n .describe(\n \"How many hours ago to include (default 24, max 720, i.e. 30 days)\",\n ),\n limit: z.number()\n .min(1).max(20).default(5)\n .describe(\"How many stories to return (1-20, default 5)\"),\n }),\n async (args) => {\n console.log(\"getRecentTopStories tool CALLED with:\", args);\n try {\n const result = await getRecentTopStories(args);\n console.log(\"getRecentTopStories RESULT:\", result);\n return result;\n } catch (e) {\n console.error(\"getRecentTopStories ERROR:\", e);\n return makeErrorResponse(e?.message || \"Unknown error\");\n }\n },\n);\n\nexport default mcp;",[],[230,254],"06ac20cc-9fce-11f0-b51b-0224a6c84d84",["D",1759436767161],"directory",[181,182,183,184,185],[230],["D",1759436767161],[],[167,67],"06ac167c-9fce-11f0-b51b-0224a6c84d84",["D",1759436767161],[179],[167],["D",1759436767161],{"_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":310,"_311":312,"_313":314,"_315":24,"_316":24,"_317":24,"_318":85,"_319":-5,"_320":-7,"_321":-7,"_322":26,"_323":24,"_324":24,"_325":-5,"_326":24,"_327":24,"_328":24,"_329":-5},"ENV",{"_281":282,"_283":284,"_285":16,"_286":287,"_288":289,"_290":291,"_292":293,"_294":295,"_296":297,"_298":299,"_300":301,"_302":303,"_304":305,"_306":307,"_308":309},"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 · index.html