# prefecthq/fastmcp-ts architecture

> Architecture diagram of the GitHub repository prefecthq/fastmcp-ts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prefecthq/fastmcp-ts
- Repository: https://github.com/prefecthq/fastmcp-ts

## Overview

fastmcp-ts is a TypeScript framework for building MCP servers, clients, and interactive server-side apps, with a CLI for running and exploring servers. The principal workflow is to define tools, resources, and prompts, serve them over MCP, and let a host or FastMCP client discover and invoke them. Server context, middleware, and authentication support request handling; separate branches cover OpenAPI-backed servers, remote-server composition, UI apps, and client-side sampling. The README documents these capabilities; unsampled modules are represented by their exact tree paths, with only documented relationships shown.

Main entry points: [`src/server/FastMCP.ts`](https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/FastMCP.ts) (Server runtime), [`src/server/apps/FastMCPApp.ts`](https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/apps/FastMCPApp.ts) (FastMCP app), [`src/client/client.ts`](https://github.com/prefecthq/fastmcp-ts/blob/main/src/client/client.ts) (Client API), [`src/server/tool.ts`](https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/tool.ts) (Tool handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP server"]
  node_server_api["FastMCP API<br/>[FastMCP.ts]"]
  node_server_run["Server runtime<br/>[FastMCP.ts]"]
  node_tool["Tool handlers<br/>[tool.ts]"]
  node_resource["Resources<br/>[resource.ts]"]
  node_prompt["Prompts<br/>[prompt.ts]"]
  node_context["Request context<br/>[context.ts]"]
  node_middleware["Middleware<br/>[middleware.ts]"]
  node_auth["Auth providers"]
end

subgraph group_client["MCP client"]
  node_client_api["Client API<br/>[client.ts]"]
  node_transport["Client transports<br/>[transports.ts]"]
  node_multi["Multi-server client<br/>[multi-server.ts]"]
  node_sampling["Sampling adapters"]
end

subgraph group_apps["Interactive apps"]
  node_app["FastMCP app<br/>[FastMCPApp.ts]"]
  node_components["UI components<br/>[components.ts]"]
  node_providers["UI providers"]
  node_generative["Generative UI<br/>[generative.ts]"]
end

subgraph group_integrations["Server integrations"]
  node_openapi["OpenAPI server"]
  node_proxy["Server proxy<br/>[proxy.ts]"]
end

subgraph group_cli["Command line"]
  node_cli["FastMCP CLI<br/>[index.ts]"]
  node_cli_commands["CLI commands"]
end

node_developer(("Server developer"))
node_host(("MCP host"))
node_mcp_sdk["MCP SDK"]
node_llm_provider["LLM provider"]

node_developer -->|"defines capabilities"| node_server_api
node_server_api -->|"registers tools"| node_tool
node_server_api -->|"registers resources"| node_resource
node_server_api -->|"registers prompts"| node_prompt
node_server_api -->|"starts runtime"| node_server_run
node_server_run -->|"serves MCP"| node_mcp_sdk
node_host -->|"sends requests"| node_server_run
node_server_run -->|"dispatches calls"| node_tool
node_server_run -->|"dispatches reads"| node_resource
node_server_run -->|"dispatches requests"| node_prompt
node_server_run -->|"applies middleware"| node_middleware
node_server_run -->|"verifies access"| node_auth
node_tool -->|"uses context"| node_context
node_developer -->|"connects client"| node_client_api
node_client_api -->|"resolves transport"| node_transport
node_transport -->|"exchanges MCP"| node_server_run
node_client_api -->|"handles sampling"| node_sampling
node_sampling -.->|"requests completion"| node_llm_provider
node_client_api -->|"supports multi-server"| node_multi
node_developer -->|"defines app"| node_app
node_app -->|"renders component tree"| node_components
node_app -->|"mounts providers"| node_providers
node_app -->|"enables composition"| node_generative
node_app -->|"uses server"| node_server_api
node_developer -->|"creates API server"| node_openapi
node_openapi -->|"registers MCP routes"| node_server_api
node_developer -->|"creates proxy"| node_proxy
node_proxy -->|"mounts remote server"| node_server_api
node_developer -->|"runs commands"| node_cli
node_cli -->|"dispatches commands"| node_cli_commands
node_cli_commands -->|"runs or inspects"| node_server_run

click node_server_api "https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/FastMCP.ts"
click node_server_run "https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/FastMCP.ts"
click node_tool "https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/tool.ts"
click node_resource "https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/resource.ts"
click node_prompt "https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/prompt.ts"
click node_context "https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/context.ts"
click node_middleware "https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/middleware.ts"
click node_auth "https://github.com/prefecthq/fastmcp-ts/tree/main/src/server/auth"
click node_client_api "https://github.com/prefecthq/fastmcp-ts/blob/main/src/client/client.ts"
click node_transport "https://github.com/prefecthq/fastmcp-ts/blob/main/src/client/transports.ts"
click node_multi "https://github.com/prefecthq/fastmcp-ts/blob/main/src/client/multi-server.ts"
click node_sampling "https://github.com/prefecthq/fastmcp-ts/tree/main/src/client/sampling"
click node_app "https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/apps/FastMCPApp.ts"
click node_components "https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/apps/components.ts"
click node_providers "https://github.com/prefecthq/fastmcp-ts/tree/main/src/server/apps/providers"
click node_generative "https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/apps/generative.ts"
click node_openapi "https://github.com/prefecthq/fastmcp-ts/tree/main/src/server/openapi"
click node_proxy "https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/proxy.ts"
click node_cli "https://github.com/prefecthq/fastmcp-ts/blob/main/src/cli/index.ts"
click node_cli_commands "https://github.com/prefecthq/fastmcp-ts/tree/main/src/cli/commands"

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_server_api,node_server_run,node_tool,node_resource,node_prompt,node_context,node_middleware,node_auth toneBlue
class node_client_api,node_transport,node_multi,node_sampling toneAmber
class node_app,node_components,node_providers,node_generative,node_developer toneMint
class node_openapi,node_proxy toneRose
class node_cli,node_cli_commands,node_host,node_mcp_sdk,node_llm_provider toneIndigo
```

## Components

### MCP server

- [FastMCP API](https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/FastMCP.ts): `src/server/FastMCP.ts`
- [Server runtime](https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/FastMCP.ts): `src/server/FastMCP.ts`
- [Tool handlers](https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/tool.ts): `src/server/tool.ts`
- [Resources](https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/resource.ts): `src/server/resource.ts`
- [Prompts](https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/prompt.ts): `src/server/prompt.ts`
- [Request context](https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/context.ts): `src/server/context.ts`
- [Middleware](https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/middleware.ts): `src/server/middleware.ts`
- [Auth providers](https://github.com/prefecthq/fastmcp-ts/tree/main/src/server/auth): `src/server/auth`

### MCP client

- [Client API](https://github.com/prefecthq/fastmcp-ts/blob/main/src/client/client.ts): `src/client/client.ts`
- [Client transports](https://github.com/prefecthq/fastmcp-ts/blob/main/src/client/transports.ts): `src/client/transports.ts`
- [Multi-server client](https://github.com/prefecthq/fastmcp-ts/blob/main/src/client/multi-server.ts): `src/client/multi-server.ts`
- [Sampling adapters](https://github.com/prefecthq/fastmcp-ts/tree/main/src/client/sampling): `src/client/sampling`

### Interactive apps

- [FastMCP app](https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/apps/FastMCPApp.ts): `src/server/apps/FastMCPApp.ts`
- [UI components](https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/apps/components.ts): `src/server/apps/components.ts`
- [UI providers](https://github.com/prefecthq/fastmcp-ts/tree/main/src/server/apps/providers): `src/server/apps/providers`
- [Generative UI](https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/apps/generative.ts): `src/server/apps/generative.ts`

### Server integrations

- [OpenAPI server](https://github.com/prefecthq/fastmcp-ts/tree/main/src/server/openapi): `src/server/openapi`
- [Server proxy](https://github.com/prefecthq/fastmcp-ts/blob/main/src/server/proxy.ts): `src/server/proxy.ts`

### Command line

- [FastMCP CLI](https://github.com/prefecthq/fastmcp-ts/blob/main/src/cli/index.ts): `src/cli/index.ts`
- [CLI commands](https://github.com/prefecthq/fastmcp-ts/tree/main/src/cli/commands): `src/cli/commands`

### Other components

- **Server developer**
- **MCP host**
- **MCP SDK**
- **LLM provider**

## Connections

- Server developer → FastMCP API: defines capabilities
- FastMCP API → Tool handlers: registers tools
- FastMCP API → Resources: registers resources
- FastMCP API → Prompts: registers prompts
- FastMCP API → Server runtime: starts runtime
- Server runtime → MCP SDK: serves MCP
- MCP host → Server runtime: sends requests
- Server runtime → Tool handlers: dispatches calls
- Server runtime → Resources: dispatches reads
- Server runtime → Prompts: dispatches requests
- Server runtime → Middleware: applies middleware
- Server runtime → Auth providers: verifies access
- Tool handlers → Request context: uses context
- Server developer → Client API: connects client
- Client API → Client transports: resolves transport
- Client transports → Server runtime: exchanges MCP
- Client API → Sampling adapters: handles sampling
- Sampling adapters → LLM provider: requests completion
- Client API → Multi-server client: supports multi-server
- Server developer → FastMCP app: defines app
- FastMCP app → UI components: renders component tree
- FastMCP app → UI providers: mounts providers
- FastMCP app → Generative UI: enables composition
- FastMCP app → FastMCP API: uses server
- Server developer → OpenAPI server: creates API server
- OpenAPI server → FastMCP API: registers MCP routes
- Server developer → Server proxy: creates proxy
- Server proxy → FastMCP API: mounts remote server
- Server developer → FastMCP CLI: runs commands
- FastMCP CLI → CLI commands: dispatches commands
- CLI commands → Server runtime: runs or inspects