Connecting React apps to MCP servers, simplified

Cloudflare has open-sourced two tools aimed at simplifying the client side of the Model Context Protocol (MCP) ecosystem. While deploying remote MCP servers has become a one-click operation on Cloudflare, building the clients that connect to them has remained a more involved task. The new releases—a React library called use-mcp and the full source code for Cloudflare's AI Playground—are designed to close that gap.

The use-mcp library, which Cloudflare is contributing directly to the MCP project, lets developers add a useMCP() hook to any React application to establish a connection to a remote server. The core integration is minimal:

mport { useMcp } from 'use-mcp/react'
function MyComponent() {
  const { state, tools, callTool } = useMcp({
    url: 'https://mcp-server.example.com'
  })
  return <div>Your actual UI code</div>
}

By specifying just a server URL, the library handles the underlying transport protocols—including both Streamable HTTP and Server-Sent Events (SSE)—along with authentication and session state management.

Connection resilience and state exposure

The library includes built-in logic for network interruptions. It automatically manages reconnection attempts with a backoff schedule, allowing a client to recover from a dropped connection and resume where it left off. For UI feedback, the hook exposes real-time connection states such as "connecting", "ready", and "failed", eliminating the need for custom connection-handling code.

const { state } = useMcp({ url: 'https://mcp-server.example.com' })

if (state === 'connecting') {
  return <div>Establishing connection...</div>
}
if (state === 'ready') {
  return <div>Connected and ready!</div>
}
if (state === 'failed') {
  return <div>Connection failed</div>
}

Built-in OAuth support

For servers that require authorization, use-mcp implements the OAuth 2.1 flow. This includes redirecting users to a login page, securely storing the access token returned by the provider, and using that credential for subsequent API requests. The library also provides methods for users to revoke access and clear stored credentials, offering a complete authentication system without additional logic from the developer.

const { clearStorage } = useMcp({ url: 'https://mcp-server.example.com' })

// Revoke access and clear stored credentials
const handleLogout = () => {
  clearStorage() // Removes all stored tokens, client info, and auth state
}

Dynamic tools and debugging tools

Upon connection, the hook fetches the list of tools exposed by the server. If the server’s capabilities change, the client application sees the new tools automatically without requiring a code update. Each tool includes type-safe metadata about its inputs, which the client can use to validate user input before making calls.

For troubleshooting, use-mcp maintains a log array with structured, timestamped messages at debug, info, warn, and error levels. Enabling the debug option provides a detailed record of tool calls, authentication flows, and state changes, which is useful during both development and production monitoring.

Supporting current and emerging standards

Given MCP is a rapidly evolving specification, the library is designed to be forward-compatible. It supports the established SSE transport and the newer Streamable HTTP standard, automatically detecting and switching to the more recent protocol when the server supports it. Cloudflare has committed to keeping use-mcp aligned with the latest MCP standards while maintaining backward compatibility.

As a practical demonstration, the project’s examples directory includes a minimal MCP Inspector built entirely with the use-mcp hook. This interface lets developers test connections to any server URL, browse available tools, and monitor interactions through the debug logs. It is available for quick deployment:

Deploy to Cloudflare

AI Playground is now open source

Cloudflare’s AI Playground is an AI chat interface that was initially created to test different models on Workers AI. After adding MCP support, it became a full remote MCP client. With this release, the entire source code is public, allowing developers to deploy their own customized instance of the chat interface.

Deploy to Cloudflare

The playground comes with support for the latest MCP standards, including both transport methods, full OAuth flows for user sign-in and permission grants, and bearer token authentication for direct connections.

BLOG-1033 Image 2

How the playground works

The architecture combines Workers AI models with the Agents SDK and the use-mcp library for server connections. The core integration starts with const { tools: mcpTools } = useMcp(), which initializes the connection system. The tool list is initially empty until a successful connection is made, at which point the server's available tools are discovered and added automatically.

When a user sends a chat message, the playground passes the mcpTools array directly to the Workers AI model. This gives the model awareness of the available capabilities, allowing it to invoke tools as needed. For servers requiring authentication, a dedicated callback page uses onMcpAuthorization to finalize the OAuth process.

const stream = useChat({
  api: "/api/inference",
  body: {
    model: params.model,
    tools: mcpTools, // Tools from connected MCP servers
    max_tokens: params.max_tokens,
    system_message: params.system_message,
  },
})

A built-in Debug Log interface provides real-time visibility into server connections, showing connection status, authentication state, and errors. During active chat sessions, the interface displays the raw JSON payloads exchanged between the client and the MCP server, including tool invocations and their results. This is particularly valuable for developers building their own remote MCP servers, as it shows how their tools perform when integrated with different language models.

A growing, community-driven ecosystem

Cloudflare’s contribution of use-mcp to the official MCP project is intended to accelerate the development of remote MCP clients. The Cloudflare AI GitHub repository contains further working examples, including complete remote MCP servers with various authentication providers and the MCP Inspector source code.

Developers looking to build their first MCP server, integrate MCP into an existing application, or contribute to the broader ecosystem can find resources in the repository or reach out to the team for feedback and collaboration.

BLOG-2812 Image 1