diff --git a/docs/build/auth.mdx b/docs/build/auth.mdx index 4888b531..b766e2ab 100644 --- a/docs/build/auth.mdx +++ b/docs/build/auth.mdx @@ -77,7 +77,7 @@ const server = new McpServer({ name: "personal-shopper", version: "0.0.1" }, {}) .registerTool(/* create-checkout … */); ``` -The endpoint values come from your OAuth provider's documentation. `resourceServerUrl` is this server's public URL: localhost in development, the tunnel URL when testing in a host, your domain in production. +The endpoint values come from your OAuth provider's documentation. `resourceServerUrl` is this server's public URL: localhost in development, the [tunnel](/test/tunnel) URL when testing in a host, your domain in production. ## Verify Tokens with a Middleware @@ -147,7 +147,7 @@ server .registerTool(/* create-checkout … */); ``` -### Declare Public Tools +### Declare Tool Visibility Three declarations cover the combinations: @@ -194,6 +194,10 @@ server.registerTool( ); ``` + + You now know how to authenticate users. Learn how to test your MCP App in the next chapter. + + ## Go Further diff --git a/docs/build/index.mdx b/docs/build/index.mdx new file mode 100644 index 00000000..b914ea31 --- /dev/null +++ b/docs/build/index.mdx @@ -0,0 +1,29 @@ +--- +title: "Build Your App" +description: "The four decisions that make an MCP App" +icon: "drafting-compass" +--- + +Building an MCP App means answering four questions: what the model can do, what the user sees, what the model knows, and who is asking. Each page below covers one, in build order, on the same running example: a personal shopper with a product carousel and an authenticated checkout. + +| Define | Page | Core APIs | +|------------|------|-----------| +| What the model can do | [Register Tools](/build/tools) | `registerTool` | +| What the user sees | [Create Views](/build/view) | `useToolInfo`, `useCallTool` | +| What the model knows | [Manage State](/build/state) | `useViewState`, `data-llm` | +| Who is asking | [Authenticate Users](/build/auth) | `requireBearerAuth`, `securitySchemes` | + + + + Define what humans and agents can do + + + Craft interactive UIs rendered in conversation + + + Decide what the model sees + + + Know who's behind every tool call + + diff --git a/docs/build/state.mdx b/docs/build/state.mdx index 792d5ce7..f3da6117 100644 --- a/docs/build/state.mdx +++ b/docs/build/state.mdx @@ -128,9 +128,11 @@ export default function Carousel() { } ``` -This is what lets the user speak in references: "what do you think of this one?". The model resolves *this one* from the `data-llm` narration. +This is what lets the user speak in references: "what do you think of this one?". The model resolves *this one* from the `data-llm` narration. Nest `data-llm` on inner elements and the model receives an indented outline of the screen. -Nest `data-llm` on inner elements and the model receives an indented outline of the screen. + + You now know how to manage state. Learn who's behind every tool call in the next chapter. + ## Go Further diff --git a/docs/build/tools.mdx b/docs/build/tools.mdx index 5ed30210..09b9a427 100644 --- a/docs/build/tools.mdx +++ b/docs/build/tools.mdx @@ -1,7 +1,7 @@ --- title: "Register Tools" description: "Define what humans and agents can do" -icon: "tools" +icon: "wrench" --- Tools Illustration @@ -271,6 +271,10 @@ export default function Carousel() { Each model call to the tool mounts a fresh view instance. Tools without `view` are headless: data, no UI. + + You now know how to register tools. Learn what happens inside the view in the next chapter. + + ## Go Further diff --git a/docs/build/view.mdx b/docs/build/view.mdx index a82e3d59..3faf5c4f 100644 --- a/docs/build/view.mdx +++ b/docs/build/view.mdx @@ -197,9 +197,9 @@ server.registerTool( {/* @todo: full csp reference */} -## Manage State - -Reading output and calling tools cover a view's request side. Everything in between (a cart filling up, a selection, a draft) is state. And it moves both ways: the user changes it by interacting, and the model can change it too, by triggering a tool the view registered. Held by the view, shared with the model, restored across remounts: that's [the next chapter](/build/state). + + You now know how to create views. Learn what the view holds between tool calls, and who sees it, in the next chapter. + ## Go Further diff --git a/docs/docs.json b/docs/docs.json index 370d3224..da14cb5b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -22,7 +22,7 @@ "tabs": [ { "tab": "Documentation", - "groups": [ + "pages": [ { "group": "Get Started", "icon": "rocket", @@ -35,13 +35,28 @@ { "group": "Build", "icon": "drafting-compass", + "root": "build/index", "pages": [ "build/tools", "build/view", "build/state", "build/auth" - ] + ], + "expanded": true + }, + { + "group": "Test", + "icon": "test-tube-diagonal", + "root": "test/index", + "pages": [ + "test/devtools", + "test/tunnel", + "test/playground", + "test/audit" + ], + "expanded": true }, + "ship", { "group": "Get Started (legacy)", "icon": "rocket", @@ -96,12 +111,18 @@ { "group": "DevTools (legacy)", "icon": "wrench", - "pages": ["devtools/skills", "devtools/devtools"] + "pages": [ + "devtools/skills", + "devtools/devtools" + ] }, { "group": "Resources (legacy)", "icon": "circle-question", - "pages": ["faq", "telemetry"] + "pages": [ + "faq", + "telemetry" + ] } ] }, @@ -111,17 +132,24 @@ { "group": "Overview", "icon": "house", - "pages": ["api-reference"] + "pages": [ + "api-reference" + ] }, { "group": "CLI", "icon": "terminal", - "pages": ["api-reference/cli"] + "pages": [ + "api-reference/cli" + ] }, { "group": "Server", "icon": "server", - "pages": ["api-reference/mcp-server", "api-reference/register-tool"] + "pages": [ + "api-reference/mcp-server", + "api-reference/register-tool" + ] }, { "group": "Hooks", @@ -177,7 +205,10 @@ "examples", { "group": "Basic", - "pages": ["examples/starter", "examples/everything"] + "pages": [ + "examples/starter", + "examples/everything" + ] }, { "group": "Use cases", @@ -201,7 +232,10 @@ }, { "group": "UI and Component libraries", - "pages": ["examples/manifest-ui", "examples/generative-ui"] + "pages": [ + "examples/manifest-ui", + "examples/generative-ui" + ] } ] } @@ -293,5 +327,8 @@ }, "interaction": { "drilldown": false + }, + "icons": { + "library": "lucide" } } diff --git a/docs/get-started/architecture.mdx b/docs/get-started/architecture.mdx index 8af9a88d..cd32158a 100644 --- a/docs/get-started/architecture.mdx +++ b/docs/get-started/architecture.mdx @@ -188,4 +188,17 @@ Install it now: ```bash npx skills add alpic-ai/skybridge -s skybridge -``` \ No newline at end of file +``` + +## Go Further + + + Learn everything that makes great MCP Apps + + + Validate your app at every step + + + Deploy your app to a stable, public URL + + diff --git a/docs/get-started/introduction.mdx b/docs/get-started/introduction.mdx index 58532bae..fe0faeaa 100644 --- a/docs/get-started/introduction.mdx +++ b/docs/get-started/introduction.mdx @@ -51,18 +51,18 @@ MCP Apps introduce a fundamental shift: unlike bidirectional web apps, they are {/* @todo: turn those into tiles with images */} - + Design experiences leveraging model intelligence. - + Define what humans and agents can see and do. - + Craft interactive UIs rendered in conversation. -Skybridge is built around all three; it's the fastest, most complete way to build full-fledged MCP Apps. Protocol, authentication, and host support are baked in. It comes with a dead-simple architecture and a complete tooling suite, including HMR, emulator, tunneling, playground, and deployment. Your sole focus: what makes your app great. +Skybridge is built around all three; it's the fastest, most complete way to build full-fledged MCP Apps. Protocol, authentication, and host support are baked in. It comes with a dead-simple architecture and a complete tooling suite, including HMR, [emulator](/test/devtools), [tunneling](/test/tunnel), [playground](/test/playground), and [deployment](/ship). Your sole focus: what makes your app great. ## The AI Sidekick of Your AI Sidekick @@ -72,4 +72,17 @@ Install it now: ```bash npx skills add alpic-ai/skybridge -s skybridge -``` \ No newline at end of file +``` + +## Go Further + + + Build, test, and deploy your first MCP App + + + Design conversational experiences leveraging model intelligence + + + Learn everything that makes great MCP Apps + + diff --git a/docs/get-started/quickstart.mdx b/docs/get-started/quickstart.mdx index 98a75dc5..0c5d0b67 100644 --- a/docs/get-started/quickstart.mdx +++ b/docs/get-started/quickstart.mdx @@ -1,14 +1,13 @@ --- title: "Quickstart" description: "Build, test, and deploy your first MCP App" -icon: "bolt" -iconType: "regular" +icon: "zap" --- Quickstart Illustration To get a running codebase right away, you can scaffold a project from our templates. They come pre-configured with: - a working MCP server -- a complete development environment with a local emulator, file watching, and hot module reload. +- a complete development environment with a local emulator, file watching, and hot module reload Prerequisite: Skybridge runs on [Node 24+](https://nodejs.org/en/download) @@ -28,9 +27,9 @@ The default `demo` template comes with two tools: Tools are defined in `server.ts`, UI components in the `views` directory. Tools are bound to views in the tool definition. - + To scaffold a bare-bones project without tools or view placeholders, select the `blank` template. - + ## Run Locally @@ -56,15 +55,15 @@ deno task dev This spins up two routes: - `http://localhost:3000/mcp`: the MCP server your app is running on -- `http://localhost:3000/`: the DevTools for testing and debugging your app +- `http://localhost:3000/`: the [DevTools](/test/devtools) for testing and debugging your app - + **Updates to your codebase are reflected right away:** server and UI components are reloaded on file save. - + ## Connect to ChatGPT and Claude -You can plug your locally running server directly into AI hosts by exposing your app on the internet. To do so, start the dev server with an Alpic tunnel: +You can plug your locally running server directly into AI hosts by exposing your app on the internet. To do so, start the dev server with a [tunnel](/test/tunnel): ```bash npm @@ -86,11 +85,9 @@ deno task dev --tunnel You'll be provided a public URL (e.g., `https://superb-marmot-fondue-420.alpic.dev/mcp`) to register your server as a ChatGPT app or a Claude connector. - -[Alpic tunnel](https://docs.alpic.ai/cli/tunnel) comes with a free LLM Playground on `/try`. No config needed: it's already wired to your local server. - - -{/* @todo: link test page */} + +[Alpic tunnel](https://docs.alpic.ai/cli/tunnel) comes with a free [LLM Playground](/test/playground) on `/try`. No config needed: it's already wired to your local server. + ## Ship @@ -116,4 +113,15 @@ deno task deploy After deployment succeeds, the CLI prints the app's public URL. You're now live! -{/* @todo: link deploy page */} \ No newline at end of file +## Go Further + + + Design conversational experiences leveraging model intelligence + + + Learn everything that makes great MCP Apps + + + Validate your app at every step + + diff --git a/docs/images/audit-screenshot.png b/docs/images/audit-screenshot.png new file mode 100644 index 00000000..541f181c Binary files /dev/null and b/docs/images/audit-screenshot.png differ diff --git a/docs/images/audit.png b/docs/images/audit.png new file mode 100644 index 00000000..912bf0ac Binary files /dev/null and b/docs/images/audit.png differ diff --git a/docs/images/deploy.png b/docs/images/deploy.png new file mode 100644 index 00000000..161ca16e Binary files /dev/null and b/docs/images/deploy.png differ diff --git a/docs/images/devtools-screenshot.png b/docs/images/devtools-screenshot.png new file mode 100644 index 00000000..154ecd6c Binary files /dev/null and b/docs/images/devtools-screenshot.png differ diff --git a/docs/images/devtools.png b/docs/images/devtools.png new file mode 100644 index 00000000..7899457a Binary files /dev/null and b/docs/images/devtools.png differ diff --git a/docs/images/playground-screenshot.png b/docs/images/playground-screenshot.png new file mode 100644 index 00000000..9dd1dd9d Binary files /dev/null and b/docs/images/playground-screenshot.png differ diff --git a/docs/images/playground.png b/docs/images/playground.png new file mode 100644 index 00000000..d83541ef Binary files /dev/null and b/docs/images/playground.png differ diff --git a/docs/images/tunnel.png b/docs/images/tunnel.png new file mode 100644 index 00000000..530a56bd Binary files /dev/null and b/docs/images/tunnel.png differ diff --git a/docs/ship.mdx b/docs/ship.mdx new file mode 100644 index 00000000..cf371581 --- /dev/null +++ b/docs/ship.mdx @@ -0,0 +1,135 @@ +--- +title: "Ship" +description: "Deploy your app to a stable, public URL" +icon: "cloud-upload" +--- +Deploy Illustration + +A deployed MCP App is a server on a public URL: hosts connect to `https://your-domain.com/mcp` and the built views are served from the same origin. + +Two commands take it there: + +- `skybridge build` compiles the views and the server into `dist/` +- `skybridge start` runs the result with `NODE_ENV=production`: pre-built assets on `/assets`, the MCP server on `/mcp`, dev tooling excluded + +Run them on any Node.js-compatible infrastructure, or pick a platform that automates them: + +## Alpic + +[Alpic](https://alpic.ai) is the preferred deployment target: a cloud platform built for MCP Apps, by the company behind Skybridge. Deployed apps get MCP analytics, logs, insights, and a public playground. + +Deploying is free, and one command away from any Skybridge project: + + +```bash npm +npm run deploy +``` +```bash pnpm +pnpm run deploy +``` +```bash yarn +yarn deploy +``` +```bash bun +bun run deploy +``` +```bash deno +deno task deploy +``` + + +For continuous deployment, push your app to GitHub and connect the repository from [app.alpic.ai](https://app.alpic.ai): every commit then ships automatically. + + +Alpic also ships its own [MCP App](https://docs.alpic.ai/features/mcp-server) to manage your deployments from any MCP client: connect to `https://mcp.alpic.ai/mcp`. + + +## Cloudflare Workers + +Skybridge runs on Cloudflare Workers via [Wrangler](https://developers.cloudflare.com/workers/wrangler/install-and-update/) and the `nodejs_compat` runtime. Static assets (your built views) are served by Cloudflare's edge directly; the worker handles `/mcp` traffic and any other dynamic routes. + +Add a `wrangler.jsonc` at your project root: + +```jsonc wrangler.jsonc +{ + "name": "your-skybridge-app", + "main": "dist/__entry.js", + "compatibility_date": "2025-09-01", + "compatibility_flags": ["nodejs_compat"], + "assets": { "directory": "dist/assets" }, + "define": { + "process.env.NODE_ENV": "\"production\"" + } +} +``` + +Each setting is load-bearing: + +- `compatibility_date >= 2025-09-01` and `nodejs_compat`: enable `cloudflare:node`'s `httpServerHandler`, which Skybridge uses to bridge the Express app to the Workers fetch event. +- `assets.directory`: points at the views built by `skybridge build`. Cloudflare serves these at the edge before requests reach your worker. +- `define.process.env.NODE_ENV`: forces production mode even under `wrangler dev`. Without it, wrangler defaults to `development` locally and Skybridge's dev tooling (Vite, the DevTools server) gets pulled into the worker bundle, where neither runs. + +Then build and deploy: + + +```bash npm +npm run build +npx wrangler deploy +``` +```bash pnpm +pnpm build +pnpm dlx wrangler deploy +``` +```bash yarn +yarn build +yarn dlx wrangler deploy +``` +```bash bun +bun run build +bunx wrangler deploy +``` + + + +`wrangler dev` runs your worker in workerd on your machine, the same runtime as production, not a Node.js fallback. Use `skybridge dev` for fast iteration with HMR; use `wrangler dev` to validate the production worker bundle before shipping. + + +## Docker + +Projects created with `npx skybridge create` include a multi-stage `Dockerfile`, so you can self-host on any container platform: + +```bash +docker build -t my-app . +docker run -p 3000:3000 my-app +``` + + +The package manager is detected from the lockfile (`package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`). Bun and Deno are not supported yet: adapt the build stage inside the Dockerfile. + + +## Vercel + +`skybridge build` emits a [Build Output API](https://vercel.com/docs/build-output-api) tree under `.vercel/output/`: a bundled serverless function, the static asset tree, and the routing config. No `vercel.json` required. + + +```bash npm +npm run build +npx vercel deploy --prebuilt +``` +```bash pnpm +pnpm build +pnpm dlx vercel deploy --prebuilt +``` +```bash yarn +yarn build +yarn dlx vercel deploy --prebuilt +``` +```bash bun +bun run build +bunx vercel deploy --prebuilt +``` + + + +`.vercel/` is gitignored by Vercel CLI convention, so the build artifacts stay out of your tracked working tree. + \ No newline at end of file diff --git a/docs/test/audit.mdx b/docs/test/audit.mdx new file mode 100644 index 00000000..47412867 --- /dev/null +++ b/docs/test/audit.mdx @@ -0,0 +1,64 @@ +--- +title: "Audit" +description: "Catch spec and platform issues before submission" +icon: "clipboard-check" +--- +Audit Illustration + +Before a platform accepts your app, the server must conform to the MCP specs, and each platform layers its own requirements on top, which differ between OpenAI and Anthropic. The Audit checks your app's conformance and performs end-to-end tests in real ChatGPT and Claude conversations, triggering tools and rendering views. + +## Run the Audit + +The Audit needs your server publicly reachable: start the [tunnel](/test/tunnel), then click **Audit** in the [DevTools](/test/devtools) header. + + +```bash npm +npm run dev -- --tunnel +``` +```bash pnpm +pnpm dev --tunnel +``` +```bash yarn +yarn dev --tunnel +``` +```bash bun +bun dev --tunnel +``` +```bash deno +deno task dev --tunnel +``` + + + +The Audit is powered by [Alpic Beacon](https://docs.alpic.ai/testing/beacon). It can also be launched from [beacon.alpic.ai](https://beacon.alpic.ai) with your server's public URL, or via the [Alpic CLI](https://docs.alpic.ai/cli/tunnel). + + +## What It Checks + +- **MCP protocol**: tool and resource conformance with the official specification. +- **MCP Apps**: view resource requirements (metadata, Content Security Policy, annotations) for both ChatGPT and Claude. +- **Platform requirements**: each platform's own submission guidelines. +- **App behavior**: the app actually works, verified by triggering tools and rendering views in real ChatGPT and Claude conversations. + + +Audit Illustration + + +The report returns an overall score, a readiness status per platform, and the issues found, each with its severity (error, warning, info), the affected component, and the solution. **Improve your score** turns the report into a prompt for your coding agent to fix them all. + +## Limitation + +OAuth-protected servers aren't supported yet. + +## Go Further + + + Call tools and render views locally, without a host + + + Expose your local server to real hosts + + + Chat with a real model running your app + + diff --git a/docs/test/devtools.mdx b/docs/test/devtools.mdx new file mode 100644 index 00000000..3f508c78 --- /dev/null +++ b/docs/test/devtools.mdx @@ -0,0 +1,85 @@ +--- +title: "DevTools" +description: "Call tools and render views locally, without a host" +icon: "square-dashed-mouse-pointer" +--- +{/* @todo: devtools illustration asset */} +DevTools Illustration + +Testing through a real host means exposing a public URL, registering a connector, starting a conversation, and prompting the model until it calls the right tool. DevTools cuts that loop down to a file save: it runs locally, emulates the host runtime, and lets you call tools directly, no model or host involved. + +## Start the Emulator + +DevTools ships with the dev server. In a scaffolded project (`npx skybridge create`), start it from the project root: + + +```bash npm +npm run dev +``` +```bash pnpm +pnpm dev +``` +```bash yarn +yarn dev +``` +```bash bun +bun dev +``` +```bash deno +deno task dev +``` + + +Two routes come up: +- `http://localhost:3000/mcp`: your MCP server +- `http://localhost:3000/`: the DevTools + +Every tool registered on the server appears in the sidebar automatically, and edits to the server or the views reload the preview on save. + +## Explore the Features + +Select a tool in the sidebar and DevTools gives you the full exchange: + + +DevTools Illustration + + +- **Tool controls**: generated from the tool's input schema. Inputs can be saved and re-run from the tool header. +- **Tool output**: the raw server response (`content`, `structuredContent`, `_meta`), with status, latency, and payload size. +- **State inspector**: the view state as a JSON tree, updated as the view mutates it. +- **View preview**: the rendered view, with live controls to switch display mode, theme, locale, and device type; the preview updates immediately. +- **Call logs**: every runtime API call the view makes (`setViewState`, `callTool`, `requestDisplayMode`) with its arguments and responses. + +## Limitations + +DevTools emulates, and three gaps separate the emulation from production: + +- **No model**: you pick the tool and type the arguments yourself. Tool selection, the prompt surface (names, descriptions, schemas), and follow-up messages are never exercised. +- **One runtime**: as of today the preview mocks the Apps SDK runtime. MCP Apps-specific features are not yet supported. +- **Loose CSP**: external resources blocked by hosts in production may load locally. + +## Custom Integration + +Projects created with `npx skybridge create` serve DevTools automatically. If you added Skybridge to an existing Express app instead, register the two DevTools middlewares yourself: + +```ts server.ts +import { devtoolsStaticServer, viewsDevServer } from "skybridge/server"; + +if (process.env.NODE_ENV !== "production") { + app.use(await devtoolsStaticServer()); + app.use(await viewsDevServer()); +} +``` + +## Go Further + + + Expose your local server to real hosts + + + Chat with a real model running your app + + + Catch spec and platform issues before submission + + \ No newline at end of file diff --git a/docs/test/index.mdx b/docs/test/index.mdx new file mode 100644 index 00000000..ffd6ce27 --- /dev/null +++ b/docs/test/index.mdx @@ -0,0 +1,29 @@ +--- +title: "Test Your App" +description: "Pick the right tool for what you're testing" +icon: "test-tube-diagonal" +--- + +Testing an MCP App means assessing how well it integrates with the host, interacts with the model, and responds to the user. The tools below put these actors in the loop, each trading setup for fidelity. + +| To | Use | Real model | Real host | Interactive | +|-------------|-----|------------|-----------|-------------| +| Iterate on tools and views | [DevTools](/test/devtools) | | | | +| Verify behavior in ChatGPT and Claude | [Tunnel](/test/tunnel) | | | | +| Check what the model does with your app | [Playground](/test/playground) | | | | +| Validate before submission | [Audit](/test/audit) | | | | + + + + Call tools and render views locally, without a host + + + Expose your local server to real hosts + + + Chat with a real model running your app + + + Catch spec and platform issues before submission + + diff --git a/docs/test/playground.mdx b/docs/test/playground.mdx new file mode 100644 index 00000000..782fb524 --- /dev/null +++ b/docs/test/playground.mdx @@ -0,0 +1,62 @@ +--- +title: "Playground" +description: "Chat with a real model running your app" +icon: "message-circle" +--- +Playground Illustration + +Putting a real model in the loop normally means registering your app in a host. The Playground skips that: a chat wired to your local server, where a real LLM uses your tools and the views render inline. + +## Start the Playground + +The Playground comes with the [tunnel](/test/tunnel). Start it with the `--tunnel` flag (or toggle **Tunnel** in the [DevTools](/test/devtools) header): + + +```bash npm +npm run dev -- --tunnel +``` +```bash pnpm +pnpm dev --tunnel +``` +```bash yarn +yarn dev --tunnel +``` +```bash bun +bun dev --tunnel +``` +```bash deno +deno task dev --tunnel +``` + + +Your local server becomes publicly available, and so does the Playground: it runs on the tunnel URL suffixed with `/try` (e.g., `https://cool-marmot-fondue-420.alpic.dev/try`). Anyone with the link can open it from any browser and chat with your app. + +## Exercise the Model Loop + +With a model in the loop, the prompt surface and the state sync become testable: + + + Playground Illustration + + +- **Tool selection**: assess what the model understands from your tool names and descriptions. +- **Argument filling**: check how it fills inputs from your schemas. +- **Narration**: see how it presents your tool outputs in the conversation. +- **State**: verify what it picks up from the view state on its next turn. + +## Limitations + +The Playground is not ChatGPT or Claude. Host specifics (model behavior, [state push policies](/build/state#decide-who-sees-what), view feature support) still need a real host. + +## Go Further + + + Call tools and render views locally, without a host + + + Expose your local server to real hosts + + + Catch spec and platform issues before submission + + diff --git a/docs/test/tunnel.mdx b/docs/test/tunnel.mdx new file mode 100644 index 00000000..80ef06bb --- /dev/null +++ b/docs/test/tunnel.mdx @@ -0,0 +1,77 @@ +--- +title: "Tunnel" +description: "Expose your local server to real hosts" +icon: "globe" +--- +Tunnel Illustration + +ChatGPT and Claude connect to MCP servers over the internet, and your dev server lives on localhost. The tunnel bridges the two: it exposes your local server on a public URL, so real hosts run your app while it keeps reloading on every file save. + + +Desktop MCP clients (VSCode, Goose, Postman, MCPJam) connect directly to `http://localhost:3000/mcp`: no tunnel needed. + + +## Start the Tunnel + +Pass the `--tunnel` flag to the dev server, or toggle **Tunnel** in the [DevTools](/test/devtools) header: + + +```bash npm +npm run dev -- --tunnel +``` +```bash pnpm +pnpm dev --tunnel +``` +```bash yarn +yarn dev --tunnel +``` +```bash bun +bun dev --tunnel +``` +```bash deno +deno task dev --tunnel +``` + + +Skybridge runs an [Alpic tunnel](https://docs.alpic.ai/cli/tunnel), then prints your public URL (e.g., `https://cool-marmot-fondue-420.alpic.dev/mcp`). + +## Connect to Hosts + +### ChatGPT + +1. Go to **Profile → Apps → Create app** +2. Enter the printed `/mcp` URL +3. Click **Create**, then select your app with the **+** button in a new conversation + + +Creating apps requires a Plus plan or above, with developer mode enabled (**Settings → Apps → Advanced settings → Developer mode**). + + +### Claude + +1. Go to **Customize → Connectors → Add custom connector** +2. Enter your app name and the printed `/mcp` URL +3. Click **Add**, then enable the connector in a new conversation + +## Iterate Without Reconnecting + +The Alpic tunnel URL is stable across restarts: register the app or connector once. Hot reload works through it too: view edits show up in the host on save, on desktop and mobile alike. + + +## Limitation + +Hosts cache your tool definitions at registration. When the server schema changes (a tool added or renamed, an input schema edited), refresh the app or connector in the host so the model sees the new definitions. + +## Go Further + + + Call tools and render views locally, without a host + + + Chat with a real model running your app + + + Catch spec and platform issues before submission + + +