# microsoft/mcp-for-beginners architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/mcp-for-beginners
- Repository: https://github.com/microsoft/mcp-for-beginners

## Overview

This repository is a hands-on MCP learning curriculum, not one integrated runtime application. Its principal workflow teaches a client to discover and invoke server tools, optionally using an LLM to choose a tool, then return the result. Separate lessons extend that pattern with transports, authentication, UI resources, sampling, and external services. The graph focuses on representative examples; unsampled lesson wiring is omitted rather than inferred.

Main entry points: [`03-GettingStarted/03-llm-client/solution/dotnet/Program.cs`](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/03-llm-client/solution/dotnet/Program.cs) (LLM MCP client), [`03-GettingStarted/01-first-server/solution/python/server.py`](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/01-first-server/solution/python/server.py) (Basic tool server), [`05-AdvancedTopics/web-search-mcp/server.py`](https://github.com/microsoft/mcp-for-beginners/blob/main/05-AdvancedTopics/web-search-mcp/server.py) (Web-search server), [`03-GettingStarted/05-stdio-server/solution/python/server.py`](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/05-stdio-server/solution/python/server.py) (stdio server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients and models"]
  node_llm_client["LLM MCP client<br/>[Program.cs]"]
end

subgraph group_servers["MCP servers"]
  node_basic_server["Basic tool server<br/>[server.py]"]
  node_stdio_server["stdio server<br/>[server.py]"]
  node_advanced_server["Advanced tool server<br/>[server.py]"]
  node_tool_definitions["Tool definitions<br/>[__init__.py]"]
  node_http_server["HTTP streaming server<br/>[server.py]"]
  node_auth_server["Authenticated server<br/>[server.py]"]
  node_auth_util["Token validation<br/>[util.py]"]
end

subgraph group_capabilities["Protocol capabilities"]
  node_mcp_apps["MCP app server<br/>[server.ts]"]
  node_app_ui["Interactive app UI<br/>[mcp-app.ts]"]
  node_sampling_server["Sampling example<br/>[server.py]"]
end

subgraph group_integrations["External integrations"]
  node_web_search["Web-search server<br/>[server.py]"]
  node_github_server["GitHub tools server<br/>[server.py]"]
  node_local_tools["Local system tools<br/>[server.py]"]
end

node_learner(("Learner or user"))
node_model["Azure OpenAI"]
node_serpapi["SerpAPI"]

node_learner -->|"asks"| node_llm_client
node_llm_client -->|"discovers and calls tools"| node_basic_server
node_llm_client -->|"sends prompt and tool definitions"| node_model
node_model -->|"returns tool call"| node_llm_client
node_llm_client -->|"dispatches tool call"| node_basic_server
node_basic_server -->|"returns result"| node_llm_client
node_stdio_server -->|"serves over stdio"| node_learner
node_advanced_server -->|"dispatches tool handlers"| node_tool_definitions
node_auth_server -->|"validates tokens"| node_auth_util
node_http_server -->|"streams progress"| node_learner
node_web_search -->|"requests search data"| node_serpapi
node_serpapi -->|"returns results"| node_web_search
node_mcp_apps -->|"serves UI resource"| node_app_ui
node_sampling_server -->|"requests generated content"| node_model
node_github_server -->|"runs system operations"| node_local_tools

click node_llm_client "https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/03-llm-client/solution/dotnet/Program.cs"
click node_basic_server "https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/01-first-server/solution/python/server.py"
click node_stdio_server "https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/05-stdio-server/solution/python/server.py"
click node_advanced_server "https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/10-advanced/code/python/server.py"
click node_tool_definitions "https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/10-advanced/code/python/tools/__init__.py"
click node_http_server "https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/06-http-streaming/solution/python/server.py"
click node_auth_server "https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/11-simple-auth/solution/python/server.py"
click node_auth_util "https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/11-simple-auth/solution/python/util.py"
click node_web_search "https://github.com/microsoft/mcp-for-beginners/blob/main/05-AdvancedTopics/web-search-mcp/server.py"
click node_mcp_apps "https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/15-mcp-apps/code/typescript/my-app/server.ts"
click node_app_ui "https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/15-mcp-apps/code/typescript/my-app/src/mcp-app.ts"
click node_sampling_server "https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/14-sampling/solution/python/server.py"
click node_github_server "https://github.com/microsoft/mcp-for-beginners/blob/main/10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit/lab4/code/github_mcp_server/src/server.py"
click node_local_tools "https://github.com/microsoft/mcp-for-beginners/blob/main/10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit/lab4/code/github_mcp_server/src/server.py"

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_llm_client,node_learner toneBlue
class node_basic_server,node_stdio_server,node_advanced_server,node_tool_definitions,node_http_server,node_auth_server,node_auth_util toneAmber
class node_mcp_apps,node_app_ui,node_sampling_server,node_serpapi toneMint
class node_web_search,node_github_server,node_local_tools toneRose
class node_model toneIndigo
```

## Components

### Clients and models

- [LLM MCP client](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/03-llm-client/solution/dotnet/Program.cs): `03-GettingStarted/03-llm-client/solution/dotnet/Program.cs`

### MCP servers

- [Basic tool server](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/01-first-server/solution/python/server.py): `03-GettingStarted/01-first-server/solution/python/server.py`
- [stdio server](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/05-stdio-server/solution/python/server.py): `03-GettingStarted/05-stdio-server/solution/python/server.py`
- [Advanced tool server](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/10-advanced/code/python/server.py): `03-GettingStarted/10-advanced/code/python/server.py`
- [Tool definitions](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/10-advanced/code/python/tools/__init__.py): `03-GettingStarted/10-advanced/code/python/tools/__init__.py`
- [HTTP streaming server](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/06-http-streaming/solution/python/server.py): `03-GettingStarted/06-http-streaming/solution/python/server.py`
- [Authenticated server](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/11-simple-auth/solution/python/server.py): `03-GettingStarted/11-simple-auth/solution/python/server.py`
- [Token validation](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/11-simple-auth/solution/python/util.py): `03-GettingStarted/11-simple-auth/solution/python/util.py`

### Protocol capabilities

- [MCP app server](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/15-mcp-apps/code/typescript/my-app/server.ts): `03-GettingStarted/15-mcp-apps/code/typescript/my-app/server.ts`
- [Interactive app UI](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/15-mcp-apps/code/typescript/my-app/src/mcp-app.ts): `03-GettingStarted/15-mcp-apps/code/typescript/my-app/src/mcp-app.ts`
- [Sampling example](https://github.com/microsoft/mcp-for-beginners/blob/main/03-GettingStarted/14-sampling/solution/python/server.py): `03-GettingStarted/14-sampling/solution/python/server.py`

### External integrations

- [Web-search server](https://github.com/microsoft/mcp-for-beginners/blob/main/05-AdvancedTopics/web-search-mcp/server.py): `05-AdvancedTopics/web-search-mcp/server.py`
- [GitHub tools server](https://github.com/microsoft/mcp-for-beginners/blob/main/10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit/lab4/code/github_mcp_server/src/server.py): `10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit/lab4/code/github_mcp_server/src/server.py`
- [Local system tools](https://github.com/microsoft/mcp-for-beginners/blob/main/10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit/lab4/code/github_mcp_server/src/server.py): `10-StreamliningAIWorkflowsBuildingAnMCPServerWithAIToolkit/lab4/code/github_mcp_server/src/server.py`

### Other components

- **Learner or user**
- **Azure OpenAI**
- **SerpAPI**

## Connections

- Learner or user → LLM MCP client: asks
- LLM MCP client → Basic tool server: discovers and calls tools
- LLM MCP client → Azure OpenAI: sends prompt and tool definitions
- Azure OpenAI → LLM MCP client: returns tool call
- LLM MCP client → Basic tool server: dispatches tool call
- Basic tool server → LLM MCP client: returns result
- stdio server → Learner or user: serves over stdio
- Advanced tool server → Tool definitions: dispatches tool handlers
- Authenticated server → Token validation: validates tokens
- HTTP streaming server → Learner or user: streams progress
- Web-search server → SerpAPI: requests search data
- SerpAPI → Web-search server: returns results
- MCP app server → Interactive app UI: serves UI resource
- Sampling example → Azure OpenAI: requests generated content
- GitHub tools server → Local system tools: runs system operations