From 4d059e631e453cff270cf23041f6a4809e5d794d Mon Sep 17 00:00:00 2001
From: Jonathan Hefner <jonathan@hefner.pro>
Date: Sun, 25 Jan 2026 13:24:26 -0600
Subject: [PATCH] Add Testing MCP Apps guide

Document how to test MCP Apps using `basic-host` and MCP Apps-compatible
hosts like Claude.ai and VS Code Copilot. Cover debugging features for
`basic-host`, and using `cloudflared` to expose local servers for remote
hosts.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/testing-mcp-apps.md | 85 ++++++++++++++++++++++++++++++++++++++++
 typedoc.config.mjs       |  1 +
 2 files changed, 86 insertions(+)
 create mode 100644 docs/testing-mcp-apps.md

diff --git a/docs/testing-mcp-apps.md b/docs/testing-mcp-apps.md
new file mode 100644
index 00000000..b36e8620
--- /dev/null
+++ b/docs/testing-mcp-apps.md
@@ -0,0 +1,85 @@
+---
+title: Testing MCP Apps
+---
+
+# Test Your MCP App
+
+This guide covers two approaches for testing your MCP App: using the `basic-host` reference implementation for local development, or using an MCP Apps-compatible host like Claude\.ai or VS Code.
+
+## Test with basic-host
+
+The [`basic-host`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) example in this repository is a reference host implementation that lets you select a tool, call it, and see your App UI rendered in a sandboxed iframe.
+
+**Prerequisites:**
+
+- Node.js installed
+- Your MCP server running locally (e.g., at `http://localhost:3001/mcp`)
+
+**Steps:**
+
+1. Clone the repository and install dependencies:
+
+   ```bash
+   git clone https://github.com/modelcontextprotocol/ext-apps.git
+   cd ext-apps/examples/basic-host
+   npm install
+   ```
+
+2. Start basic-host, pointing it to your MCP server:
+
+   ```bash
+   SERVERS='["http://localhost:3001/mcp"]' npm start
+   ```
+
+   To connect to multiple servers, list them in the array:
+
+   ```bash
+   SERVERS='["http://localhost:3001/mcp", "http://localhost:3002/mcp"]' npm start
+   ```
+
+3. Open http://localhost:8080 in your browser.
+
+4. Select your server from the dropdown, then select a tool with UI support.
+
+5. Enter any required tool input as JSON and click "Call Tool" to see your App render.
+
+### Debugging with basic-host
+
+The basic-host UI includes collapsible panels to help you debug your App:
+
+- **Tool Input** — The JSON input sent to your tool
+- **Tool Result** — The result returned by your tool
+- **Messages** — Messages sent by your App to the model
+- **Model Context** — Context updates sent by your App
+
+For additional observability, open your browser's developer console. Basic-host logs key events with a `[HOST]` prefix, including server connections, tool calls, App initialization, and App-to-host requests.
+
+## Test with an MCP Apps-compatible host
+
+To test your App in a real conversational environment, install your MCP server in a host that supports MCP Apps:
+
+- Claude\.ai
+  - [Remote MCP servers (over HTTP)](https://claude.ai/docs/connectors/custom/remote-mcp)
+  - [Local MCP servers (over stdio)](https://claude.ai/docs/connectors/custom/desktop-extensions)
+- [VS Code Copilot](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
+
+Once your server is configured, ask the agent to perform a task related to your App-enhanced tool. For example, if you have a weather App, ask the agent "Show me the current weather."
+
+## Expose local servers with `cloudflared`
+
+Remote hosts like Claude\.ai cannot reach `localhost`. To test a local HTTP server with a remote host, use [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel/) to create a publicly accessible tunnel:
+
+1. Start your MCP server locally (e.g., at `http://localhost:3001/mcp`).
+
+2. Run `cloudflared` to expose your server:
+
+   ```bash
+   npx cloudflared tunnel --url http://localhost:3001
+   ```
+
+3. Copy the generated URL from the `cloudflared` output (e.g., `https://random-name.trycloudflare.com`).
+
+4. Add that URL as a remote MCP server in your host, appending your MCP endpoint path (e.g., `https://random-name.trycloudflare.com/mcp`).
+
+> [!NOTE]
+> The tunnel URL changes each time you restart `cloudflared`.
diff --git a/typedoc.config.mjs b/typedoc.config.mjs
index b6a76353..c9c2f63e 100644
--- a/typedoc.config.mjs
+++ b/typedoc.config.mjs
@@ -11,6 +11,7 @@ const config = {
     "docs/overview.md",
     "docs/quickstart.md",
     "docs/agent-skills.md",
+    "docs/testing-mcp-apps.md",
     "docs/patterns.md",
     "docs/migrate_from_openai_apps.md",
   ],