Skip to Content
onedef

MCP Apps

Your own UI, rendered inside Claude and ChatGPT. The same screens as your website.

An MCP App is a UI an MCP server hands to the host (Claude, ChatGPT). The host renders it in the conversation, and the UI gets its data through tool calls. With onedef it is the same screens as your website: only the transport changes.

lib/client.ts
import { createClient } from 'onedef'
import { mcpApp } from '@onedef/mcp/app'
import { rpc } from '@onedef/orpc/client'

// inside an MCP App: tool calls through the host. On the website: fetch.
export const api = createClient(contract, mcpApp() ?? rpc({ url: '/api' }))

mcpApp() knows synchronously whether the page is running inside an MCP App, because the MCP server marks the HTML it serves. The browser side is about 3 kB, with no dependencies.

With Next.js

@onedef/next builds the MCP App for you, as part of next build and next dev. You add one file next to your pages.

Wrap the Next config

next.config.ts
import { withOnedef } from '@onedef/next'

export default withOnedef(nextConfig)

Declare the app: app/mcp-app.tsx

app/mcp-app.tsx
import { defineMcpApp } from '@onedef/next/mcp-app'
import { contract } from '@/lib/contract'
import { HomeScreen } from '@/screens/home'
import { SongScreen } from '@/screens/song'

export default defineMcpApp(contract, {
  routes: {
    // path patterns to screens; params become props (SongScreen gets `slug`)
    '/': { screen: HomeScreen, openedBy: ['songs.list'] },
    '/songs/:slug': { screen: SongScreen, openedBy: ['songs.get'] },   // :slug ← the call's input.slug
  },
})

openedBy lists the tool calls that open a screen. The route's params are read from the call's input by name. A route without openedBy (just '/about': AboutScreen) is reached by navigating inside the app.

When a param's name differs from the input field, give a function per op instead:

'/tracks/:id': { screen: TrackScreen, openedBy: { 'songs.get': ({ input }) => ({ id: input.slug }) } },

A wrong operation, an input without the route's params, or a screen whose props don't match its pattern is a compile error. Next ignores this file as a route: it is the MCP App's entry.

Serve it from /mcp

app/mcp/route.ts
import { createMcpHandler } from '@onedef/mcp'
import { serveMcpApp } from '@onedef/next/server'
import { backend } from '@/lib/backend'

const handler = createMcpHandler(backend, {
  app: serveMcpApp({ tools: ['songs.list', 'songs.get'] }),   // these tool calls open the UI
})
export { handler as GET, handler as POST, handler as DELETE }

tools is checked against the contract. Every tool stays callable from inside the UI.

Ask Claude to "show me the song La Vie en rose". It calls songs_get, and your song screen opens in the conversation. The tool's result is already in the query cache, so the screen renders without a second call.

There's no Vite config and no extra script. next build produces one self-contained HTML file and ships it with the /mcp route. next dev rebuilds it as you edit.

Things that differ inside a host

  • Navigation: screens should import Link / useNavigate from your own small module that uses Next's router on the website and useMcpRouter() inside the app.
  • Embeds: hosts block nested iframes (YouTube, maps). Show a thumbnail that opens the link instead, with openLink() from @onedef/mcp/app.
  • Theme: applyHostTheme() follows the host's light or dark mode.

Without Next.js

Build your UI as one self-contained HTML file (any framework, bundled inline) and give it to the MCP handler. launch(contract) tells the UI which tool call opened it.

import { readFile } from 'node:fs/promises'

createMcpHandler(backend, {
  app: {
    html: () => readFile('mcp-app/dist/index.html', 'utf8'),
    tools: ['songs.get', 'songs.list'],   // default: every query
    csp: { resourceDomains: ['https://i.ytimg.com'] },   // origins the UI may load from
  },
})

html is needed here because the host renders your UI from that file, and only you know where your build put it. With Next.js, serveMcpApp() fills it in.

On this page