Skip to content

Commit 7fabe3c

Browse files
KludexKludex
committed
docs: restructure documentation with quickstart, concepts, and new nav
Set up the foundation for migrating documentation from README.v2.md into proper docs pages served by mkdocs. - Rewrite `docs/index.md` as a concise landing page with card grid - Add `docs/quickstart.md` with a complete getting-started guide - Fill `docs/concepts.md` with protocol architecture, primitives, transports, context, and lifecycle overview - Restructure `mkdocs.yml` nav into Server, Client, and top-level sections - Create `docs/server/` and `docs/client/` directories with placeholder pages for upcoming content - Move `docs/low-level-server.md` to `docs/server/low-level.md`
1 parent 1a943ad commit 7fabe3c

19 files changed

+370
-52
lines changed

‎docs/client/display-utilities.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Display Utilities
2+
3+
!!! warning "Under Construction"
4+
5+
This page is currently being written. Check back soon for complete documentation.

‎docs/client/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Writing MCP Clients
2+
3+
!!! warning "Under Construction"
4+
5+
This page is currently being written. Check back soon for complete documentation.

‎docs/client/parsing-results.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Parsing Tool Results
2+
3+
!!! warning "Under Construction"
4+
5+
This page is currently being written. Check back soon for complete documentation.

‎docs/concepts.md‎

Lines changed: 132 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,136 @@
11
# Concepts
22

3-
!!! warning "Under Construction"
3+
The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets you build servers that expose data
4+
and functionality to LLM applications in a standardized way. Think of it like a web API, but specifically
5+
designed for LLM interactions.
46

5-
This page is currently being written. Check back soon for complete documentation.
7+
## Architecture
68

7-
<!--
8-
- Server vs Client
9-
- Three primitives (tools, resources, prompts)
10-
- Transports (stdio, SSE, streamable HTTP)
11-
- Context and sessions
12-
- Lifecycle and state
13-
-->
9+
MCP follows a client-server architecture:
10+
11+
- **Hosts** are LLM applications (like Claude Desktop or an IDE) that initiate connections
12+
- **Clients** maintain 1:1 connections with servers, inside the host application
13+
- **Servers** provide context, tools, and prompts to clients
14+
15+
```text
16+
Host (e.g. Claude Desktop)
17+
├── Client A ↔ Server A (e.g. file system)
18+
├── Client B ↔ Server B (e.g. database)
19+
└── Client C ↔ Server C (e.g. API wrapper)
20+
```
21+
22+
## Primitives
23+
24+
MCP servers expose three core primitives:
25+
26+
### Resources
27+
28+
Resources provide data to LLMs — similar to GET endpoints in a REST API. They load information into the
29+
LLM's context without performing computation or causing side effects.
30+
31+
```python
32+
@mcp.resource("config://app")
33+
def get_config() -> str:
34+
"""Expose application configuration."""
35+
return json.dumps({"theme": "dark", "version": "2.0"})
36+
```
37+
38+
Resources can be static (fixed URI) or use URI templates for dynamic content:
39+
40+
```python
41+
@mcp.resource("users://{user_id}/profile")
42+
def get_profile(user_id: str) -> str:
43+
"""Get a user profile by ID."""
44+
return json.dumps(load_profile(user_id))
45+
```
46+
47+
See [Resources](server/resources.md) for full documentation.
48+
49+
### Tools
50+
51+
Tools let LLMs take actions — similar to POST endpoints. They perform computation, call external APIs,
52+
or produce side effects.
53+
54+
```python
55+
@mcp.tool()
56+
def send_email(to: str, subject: str, body: str) -> str:
57+
"""Send an email to the given recipient."""
58+
# ... send email logic ...
59+
return f"Email sent to {to}"
60+
```
61+
62+
Tools support structured output, progress reporting, and more. See [Tools](server/tools.md) for full documentation.
63+
64+
### Prompts
65+
66+
Prompts are reusable templates for LLM interactions. They help standardize common workflows:
67+
68+
```python
69+
@mcp.prompt()
70+
def review_code(code: str, language: str = "python") -> str:
71+
"""Generate a code review prompt."""
72+
return f"Review this {language} code:\n\n```{language}\n{code}\n```"
73+
```
74+
75+
See [Prompts](server/prompts.md) for full documentation.
76+
77+
## Transports
78+
79+
MCP supports multiple transport mechanisms for client-server communication:
80+
81+
| Transport | Use case | How it works |
82+
|---|---|---|
83+
| **Streamable HTTP** | Remote servers, production deployments | HTTP POST with optional SSE streaming |
84+
| **stdio** | Local processes, CLI tools | Communication over stdin/stdout |
85+
| **SSE** | Legacy remote servers | Server-Sent Events over HTTP (deprecated in favor of Streamable HTTP) |
86+
87+
See [Running Your Server](server/running.md) for transport configuration.
88+
89+
## Context
90+
91+
When handling requests, your functions can access a **context object** that provides capabilities
92+
like logging, progress reporting, and access to the current session:
93+
94+
```python
95+
from mcp.server.mcpserver import Context
96+
97+
@mcp.tool()
98+
async def long_task(ctx: Context) -> str:
99+
"""A tool that reports progress."""
100+
await ctx.report_progress(0, 100)
101+
# ... do work ...
102+
await ctx.report_progress(100, 100)
103+
return "Done"
104+
```
105+
106+
Context enables [logging](server/logging.md), [elicitation](server/elicitation.md),
107+
[sampling](server/sampling.md), and more. See [Context](server/context.md) for details.
108+
109+
## Server lifecycle
110+
111+
Servers support a **lifespan** pattern for managing startup and shutdown logic — for example
112+
initializing a database connection pool on startup and closing it on shutdown:
113+
114+
```python
115+
from contextlib import asynccontextmanager
116+
117+
@asynccontextmanager
118+
async def app_lifespan(server):
119+
db = await Database.connect()
120+
try:
121+
yield {"db": db}
122+
finally:
123+
await db.disconnect()
124+
125+
mcp = MCPServer("My App", lifespan=app_lifespan)
126+
```
127+
128+
See [Server](server/index.md) for more on lifecycle management.
129+
130+
## Next steps
131+
132+
- **[Quickstart](quickstart.md)** — build your first server
133+
- **[Server](server/index.md)** — `MCPServer` configuration and lifecycle
134+
- **[Tools](server/tools.md)**, **[Resources](server/resources.md)**, **[Prompts](server/prompts.md)** — dive into each primitive
135+
- **[Client](client/index.md)** — writing MCP clients
136+
- **[Authorization](authorization.md)** — securing your servers with OAuth 2.1

‎docs/index.md‎

Lines changed: 51 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,80 @@
11
# MCP Python SDK
22

3-
The **Model Context Protocol (MCP)** allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction.
3+
The **Model Context Protocol (MCP)** allows applications to provide context for LLMs in a standardized way,
4+
separating the concerns of providing context from the actual LLM interaction.
45

56
This Python SDK implements the full MCP specification, making it easy to:
67

78
- **Build MCP servers** that expose resources, prompts, and tools
8-
- **Create MCP clients** that can connect to any MCP server
9+
- **Create MCP clients** that connect to any MCP server
910
- **Use standard transports** like stdio, SSE, and Streamable HTTP
1011

11-
If you want to read more about the specification, please visit the [MCP documentation](https://modelcontextprotocol.io).
12+
## Quick example
1213

13-
## Quick Example
14-
15-
Here's a simple MCP server that exposes a tool, resource, and prompt:
16-
17-
```python title="server.py"
14+
```python
1815
from mcp.server.mcpserver import MCPServer
1916

20-
mcp = MCPServer("Test Server", json_response=True)
21-
17+
mcp = MCPServer("Demo")
2218

2319
@mcp.tool()
2420
def add(a: int, b: int) -> int:
25-
"""Add two numbers"""
21+
"""Add two numbers."""
2622
return a + b
2723

28-
29-
@mcp.resource("greeting://{name}")
30-
def get_greeting(name: str) -> str:
31-
"""Get a personalized greeting"""
32-
return f"Hello, {name}!"
33-
34-
35-
@mcp.prompt()
36-
def greet_user(name: str, style: str = "friendly") -> str:
37-
"""Generate a greeting prompt"""
38-
return f"Write a {style} greeting for someone named {name}."
39-
40-
4124
if __name__ == "__main__":
4225
mcp.run(transport="streamable-http")
4326
```
4427

45-
Run the server:
46-
4728
```bash
4829
uv run --with mcp server.py
4930
```
5031

51-
Then open the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) and connect to `http://localhost:8000/mcp`:
32+
## Getting started
5233

53-
```bash
54-
npx -y @modelcontextprotocol/inspector
55-
```
34+
1. **[Install](installation.md)** the SDK
35+
2. **[Quickstart](quickstart.md)** — build your first MCP server
36+
3. **[Concepts](concepts.md)** — understand the protocol architecture and primitives
37+
38+
## Documentation
39+
40+
<div class="grid cards" markdown>
41+
42+
- **Server**
43+
44+
---
45+
46+
Build MCP servers with tools, resources, and prompts.
47+
48+
[:octicons-arrow-right-24: Server guide](server/index.md)
49+
50+
- **Client**
51+
52+
---
53+
54+
Connect to MCP servers and invoke tools.
55+
56+
[:octicons-arrow-right-24: Client guide](client/index.md)
57+
58+
- **Authorization**
59+
60+
---
61+
62+
Secure your servers with OAuth 2.1.
63+
64+
[:octicons-arrow-right-24: Authorization](authorization.md)
65+
66+
- **Testing**
67+
68+
---
69+
70+
Test your servers with the in-memory `Client`.
5671

57-
## Getting Started
72+
[:octicons-arrow-right-24: Testing](testing.md)
5873

59-
<!-- TODO(Marcelo): automatically generate the follow references with a header on each of those files. -->
60-
1. **[Install](installation.md)** the MCP SDK
61-
2. **[Learn concepts](concepts.md)** - understand the three primitives and architecture
62-
3. **[Explore authorization](authorization.md)** - add security to your servers
63-
4. **[Use low-level APIs](low-level-server.md)** - for advanced customization
74+
</div>
6475

65-
## API Reference
76+
## Links
6677

67-
Full API documentation is available in the [API Reference](api.md).
78+
- [MCP specification](https://modelcontextprotocol.io)
79+
- [API Reference](api.md)
80+
- [Migration guide](migration.md) (v1 → v2)

‎docs/quickstart.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Quickstart
2+
3+
This guide will get you up and running with a simple MCP server in minutes.
4+
5+
## Prerequisites
6+
7+
You'll need Python 3.10+ and [uv](https://docs.astral.sh/uv/) (recommended) or pip.
8+
9+
## Create a server
10+
11+
Create a file called `server.py` with a tool, a resource, and a prompt:
12+
13+
<!-- snippet-source examples/snippets/servers/mcpserver_quickstart.py -->
14+
```python
15+
"""MCPServer quickstart example.
16+
17+
Run from the repository root:
18+
uv run examples/snippets/servers/mcpserver_quickstart.py
19+
"""
20+
21+
from mcp.server.mcpserver import MCPServer
22+
23+
# Create an MCP server
24+
mcp = MCPServer("Demo")
25+
26+
27+
# Add an addition tool
28+
@mcp.tool()
29+
def add(a: int, b: int) -> int:
30+
"""Add two numbers"""
31+
return a + b
32+
33+
34+
# Add a dynamic greeting resource
35+
@mcp.resource("greeting://{name}")
36+
def get_greeting(name: str) -> str:
37+
"""Get a personalized greeting"""
38+
return f"Hello, {name}!"
39+
40+
41+
# Add a prompt
42+
@mcp.prompt()
43+
def greet_user(name: str, style: str = "friendly") -> str:
44+
"""Generate a greeting prompt"""
45+
styles = {
46+
"friendly": "Please write a warm, friendly greeting",
47+
"formal": "Please write a formal, professional greeting",
48+
"casual": "Please write a casual, relaxed greeting",
49+
}
50+
51+
return f"{styles.get(style, styles['friendly'])} for someone named {name}."
52+
53+
54+
# Run with streamable HTTP transport
55+
if __name__ == "__main__":
56+
mcp.run(transport="streamable-http", json_response=True)
57+
```
58+
59+
_Full example: [examples/snippets/servers/mcpserver_quickstart.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/mcpserver_quickstart.py)_
60+
<!-- /snippet-source -->
61+
62+
## Run the server
63+
64+
```bash
65+
uv run --with mcp server.py
66+
```
67+
68+
The server starts on `http://localhost:8000/mcp` using Streamable HTTP transport.
69+
70+
## Connect a client
71+
72+
=== "Claude Code"
73+
74+
Add the server to [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp):
75+
76+
```bash
77+
claude mcp add --transport http my-server http://localhost:8000/mcp
78+
```
79+
80+
=== "MCP Inspector"
81+
82+
Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to explore your server interactively:
83+
84+
```bash
85+
npx -y @modelcontextprotocol/inspector
86+
```
87+
88+
In the inspector UI, connect to `http://localhost:8000/mcp`.
89+
90+
## Next steps
91+
92+
- **[Concepts](concepts.md)** — understand the protocol architecture and primitives
93+
- **[Server](server/index.md)** — learn about `MCPServer` configuration and lifecycle
94+
- **[Tools](server/tools.md)**, **[Resources](server/resources.md)**, **[Prompts](server/prompts.md)** — dive into each primitive
95+
- **[Running Your Server](server/running.md)** — transport options and deployment
96+
- **[Testing](testing.md)** — test your server with the `Client` class

‎docs/server/completions.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Completions
2+
3+
!!! warning "Under Construction"
4+
5+
This page is currently being written. Check back soon for complete documentation.

‎docs/server/context.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Context
2+
3+
!!! warning "Under Construction"
4+
5+
This page is currently being written. Check back soon for complete documentation.

‎docs/server/elicitation.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Elicitation
2+
3+
!!! warning "Under Construction"
4+
5+
This page is currently being written. Check back soon for complete documentation.

0 commit comments

Comments
 (0)