modelcontextprotocol/ext-apps
Watch
1
0
Fork
You've already forked ext-apps
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ext-apps/docs/testing-mcp-apps.md
Den Delimarsky 76f2de7b19
 Add Security documentation section and SEO improvements (#524) 
* Add Security docs section, SEO improvements, and doc site enhancements

- Add Authorization guide covering per-server and per-tool OAuth patterns
- Add CSP & CORS guide extracted from Patterns doc
- Group both under a new Security section in the documentation nav
- Replace CSP & CORS section in Patterns with cross-reference to new guide
- Rename doc site title from package name to 'MCP Apps'
- Rename 'Modules' nav section to 'API Documentation'
- Ensure Security section appears before API Documentation in TOC
- Add SEO plugin with JSON-LD structured data (TechArticle/WebPage)
- Add per-page meta descriptions from frontmatter
- Add description frontmatter to all documentation pages
- Add hostedBaseUrl for sitemap.xml generation and canonical URLs
- Normalize document page slugs to lowercase hyphenated format
- Update compressed navigation and search index data to match new slugs

* Add favicons with light/dark mode support

- Download favicons from modelcontextprotocol.io (light + dark variants)
- Inject favicon link tags into every page with correct relative paths
- Support prefers-color-scheme media queries for light/dark mode
- Include apple-touch-icon for iOS
- Copy favicon assets to output directory during doc build

* Fix HTML sanitization in SEO plugin with proper parser

Replace regex-based HTML tag stripping with htmlparser2 for
extracting plain-text descriptions from rendered pages.

* Add custom theme to align with modelcontextprotocol.io styling

- Import Inter and JetBrains Mono fonts (matching MCP site)
- Override light mode colors: pure white backgrounds, softer gray borders
- Override dark mode colors: match MCP site dark background (#0f1117)
- Taller header (3.5rem) with backdrop-blur frosted glass effect
- Sidebar: adjusted spacing, font size, and hover/active states
- Content: increased line-height (1.6), more heading breathing room
- Code blocks: JetBrains Mono, subtle border, more padding
- Fix CSS load order: custom.css now loads after theme stylesheets

* Align sidebar nav styling with modelcontextprotocol.io

- Active item: tinted blue background with blue text (matching MCP's
  primary-color tinted active state)
- Non-active items: muted gray text, subtle hover background
- Larger border-radius (0.75rem/rounded-xl) matching MCP sidebar
- Group headers: semibold with slight letter spacing
- Proper dark mode variants for all states

* Fix sidebar active item: dark gray background with bold text

* Make sidebar active item more prominent: bolder weight, stronger background

* Highlight current page in sidebar nav, normalize code font size

Inject a small script via the SEO plugin that marks the active sidebar
link with a "current" class (TypeDoc doesn't do this natively for
document pages). Uses a MutationObserver since the sidebar is populated
asynchronously. Pathname comparison strips .html extensions to support
clean-URL servers.

Also bumps code/pre font-size from 0.85em to 1em so code snippets match
the surrounding body text size.

* Split styling into dedicated plugin, fix auth terminology, improve breadcrumbs

Extract CSS cascade fix, breadcrumb labels, and sidebar nav highlighting
from the SEO plugin into a new typedoc-plugin-mcpstyle.mjs to keep
concerns separated.

Fix authorization doc: use "authorization" consistently instead of mixing
with "authentication", link to MCP spec and RFC 9728 for Protected
Resource Metadata, remove redundant spec link paragraph.

Rename "Documents" nav section to "Getting Started" and add explicit
group frontmatter to all doc pages. Breadcrumbs now show the section
name instead of duplicating the page title.
2026-03-06 13:45:15 +00:00

3.5 KiB
Raw Blame History

title group description
Testing MCP Apps Getting Started Test MCP Apps locally with the basic-host reference implementation or in production hosts like Claude.ai and VS Code.

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 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:

    git clone https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps
npm install
cd examples/basic-host

  2. Start basic-host, pointing it to your MCP server:

    SERVERS='["http://localhost:3001/mcp"]' npm start

    To connect to multiple servers, list them in the array:

    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:

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 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:

    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.