Skip to content

testing-mcp-apps.md

Latest commit

 

History

History
89 lines (57 loc) · 3.5 KB

testing-mcp-apps.md

File metadata and controls

89 lines (57 loc) · 3.5 KB
title Testing MCP Apps
group Getting Started
description 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.