# modelcontextprotocol/use-mcp architecture

> Architecture diagram of the GitHub repository modelcontextprotocol/use-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/modelcontextprotocol/use-mcp
- Repository: https://github.com/modelcontextprotocol/use-mcp

## Overview

use-mcp is a browser-side React library: an application configures the hook, which authenticates and connects to an MCP server, discovers its capabilities, then exposes tool, resource, and prompt operations. OAuth callback handling completes popup authorization; the browser provider stores OAuth state in localStorage. The source excerpts do not show every operation’s implementation or the full connection sequence, so the graph focuses on documented capabilities and excerpt-supported calls.

Main entry points: [`src/react/useMcp.ts`](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/react/useMcp.ts) (useMcp hook), [`src/auth/browser-provider.ts`](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/auth/browser-provider.ts) (OAuth provider), [`src/auth/callback.ts`](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/auth/callback.ts) (OAuth callback), [`src/index.ts`](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/index.ts) (Core exports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["React integration"]
  node_hook["useMcp hook<br/>[useMcp.ts]"]
  node_api["Hook API types<br/>[types.ts]"]
  node_assert["Runtime assertions<br/>[assert.ts]"]
end

subgraph group_connection["MCP connection"]
  node_sdk["MCP client SDK"]
  node_tools["Tool calls<br/>[useMcp.ts]"]
  node_resources["Resource access<br/>[useMcp.ts]"]
  node_prompts["Prompt access<br/>[useMcp.ts]"]
  node_transport["HTTP / SSE transport<br/>[useMcp.ts]"]
end

subgraph group_oauth["Browser OAuth"]
  node_provider["OAuth provider"]
  node_storage[("OAuth browser storage")]
  node_callback["OAuth callback<br/>[callback.ts]"]
  node_coreentry["Core exports<br/>[index.ts]"]
end

node_app(("React application"))
node_server["MCP server"]
node_authserver["OAuth authorization server"]
node_popup(("Authorization popup"))

node_app -->|"configures"| node_hook
node_hook -->|"creates and uses"| node_provider
node_hook -->|"creates"| node_transport
node_hook -->|"authenticates and connects"| node_sdk
node_transport -.->|"exchanges MCP messages"| node_server
node_hook -->|"exposes"| node_tools
node_hook -->|"exposes"| node_resources
node_hook -->|"exposes"| node_prompts
node_sdk -.->|"requests capabilities"| node_server
node_provider -->|"reads and writes"| node_storage
node_provider -->|"opens"| node_popup
node_provider -.->|"prepares authorization"| node_authserver
node_popup -->|"returns authorization code"| node_callback
node_callback -->|"reads state; saves tokens"| node_storage
node_callback -->|"reconstructs and uses"| node_provider
node_callback -->|"exchanges code via SDK"| node_authserver
node_app -->|"invokes callback handler"| node_callback
node_hook -->|"checks auth state"| node_assert
node_coreentry -->|"exports"| node_provider
node_coreentry -->|"exports"| node_callback

click node_hook "https://github.com/modelcontextprotocol/use-mcp/blob/main/src/react/useMcp.ts"
click node_api "https://github.com/modelcontextprotocol/use-mcp/blob/main/src/react/types.ts"
click node_tools "https://github.com/modelcontextprotocol/use-mcp/blob/main/src/react/useMcp.ts"
click node_resources "https://github.com/modelcontextprotocol/use-mcp/blob/main/src/react/useMcp.ts"
click node_prompts "https://github.com/modelcontextprotocol/use-mcp/blob/main/src/react/useMcp.ts"
click node_transport "https://github.com/modelcontextprotocol/use-mcp/blob/main/src/react/useMcp.ts"
click node_provider "https://github.com/modelcontextprotocol/use-mcp/blob/main/src/auth/browser-provider.ts"
click node_storage "https://github.com/modelcontextprotocol/use-mcp/blob/main/src/auth/browser-provider.ts"
click node_callback "https://github.com/modelcontextprotocol/use-mcp/blob/main/src/auth/callback.ts"
click node_assert "https://github.com/modelcontextprotocol/use-mcp/blob/main/src/utils/assert.ts"
click node_coreentry "https://github.com/modelcontextprotocol/use-mcp/blob/main/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hook,node_api,node_assert toneBlue
class node_sdk,node_tools,node_resources,node_prompts,node_transport toneAmber
class node_provider,node_storage,node_callback,node_coreentry,node_server,node_authserver toneMint
class node_app,node_popup toneIndigo
```

## Components

### React integration

- [useMcp hook](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/react/useMcp.ts): `src/react/useMcp.ts`
- [Hook API types](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/react/types.ts): `src/react/types.ts`
- [Runtime assertions](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/utils/assert.ts): `src/utils/assert.ts`

### MCP connection

- **MCP client SDK**
- [Tool calls](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/react/useMcp.ts): `src/react/useMcp.ts`
- [Resource access](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/react/useMcp.ts): `src/react/useMcp.ts`
- [Prompt access](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/react/useMcp.ts): `src/react/useMcp.ts`
- [HTTP / SSE transport](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/react/useMcp.ts): `src/react/useMcp.ts`

### Browser OAuth

- [OAuth provider](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/auth/browser-provider.ts): `src/auth/browser-provider.ts`
- [OAuth browser storage](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/auth/browser-provider.ts): `src/auth/browser-provider.ts`
- [OAuth callback](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/auth/callback.ts): `src/auth/callback.ts`
- [Core exports](https://github.com/modelcontextprotocol/use-mcp/blob/main/src/index.ts): `src/index.ts`

### Other components

- **React application**
- **MCP server**
- **OAuth authorization server**
- **Authorization popup**

## Connections

- React application → useMcp hook: configures (evidence: `README.md`)
- useMcp hook → OAuth provider: creates and uses (evidence: `src/react/useMcp.ts`)
- useMcp hook → HTTP / SSE transport: creates (evidence: `src/react/useMcp.ts`)
- useMcp hook → MCP client SDK: authenticates and connects (evidence: `src/react/useMcp.ts`)
- HTTP / SSE transport → MCP server: exchanges MCP messages
- useMcp hook → Tool calls: exposes (evidence: `README.md`)
- useMcp hook → Resource access: exposes (evidence: `README.md`)
- useMcp hook → Prompt access: exposes (evidence: `README.md`)
- MCP client SDK → MCP server: requests capabilities
- OAuth provider → OAuth browser storage: reads and writes (evidence: `src/auth/browser-provider.ts`)
- OAuth provider → Authorization popup: opens (evidence: `src/auth/browser-provider.ts`)
- OAuth provider → OAuth authorization server: prepares authorization
- Authorization popup → OAuth callback: returns authorization code (evidence: `src/auth/callback.ts`)
- OAuth callback → OAuth browser storage: reads state; saves tokens (evidence: `src/auth/callback.ts`)
- OAuth callback → OAuth provider: reconstructs and uses (evidence: `src/auth/callback.ts`)
- OAuth callback → OAuth authorization server: exchanges code via SDK (evidence: `src/auth/callback.ts`)
- React application → OAuth callback: invokes callback handler (evidence: `README.md`)
- useMcp hook → Runtime assertions: checks auth state (evidence: `src/react/useMcp.ts`)
- Core exports → OAuth provider: exports (evidence: `src/index.ts`)
- Core exports → OAuth callback: exports (evidence: `src/index.ts`)
