Add documentation structure (#1425)

Author: Kludex

docs/authorization.md

@@ -0,0 +1,5 @@
+# Authorization
+
+!!! warning "Under Construction"
+
+    This page is currently being written. Check back soon for complete documentation.

docs/concepts.md

@@ -0,0 +1,13 @@
+# Concepts
+
+!!! warning "Under Construction"
+
+    This page is currently being written. Check back soon for complete documentation.
+
+<!--
+  - Server vs Client
+  - Three primitives (tools, resources, prompts)
+  - Transports (stdio, SSE, streamable HTTP)
+  - Context and sessions
+  - Lifecycle and state
+ -->

docs/index.md

@@ -1,5 +1,57 @@
-# MCP Server
+# MCP Python SDK
 
-This is the MCP Server implementation in Python.
+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.
 
-It only contains the [API Reference](api.md) for the time being.
+This Python SDK implements the full MCP specification, making it easy to:
+
+- **Build MCP servers** that expose resources, prompts, and tools
+- **Create MCP clients** that can connect to any MCP server
+- **Use standard transports** like stdio, SSE, and Streamable HTTP
+
+If you want to read more about the specification, please visit the [MCP documentation](https://modelcontextprotocol.io).
+
+## Quick Example
+
+Here's a simple MCP server that exposes a tool, resource, and prompt:
+
+```python title="server.py"
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("Test Server")
+
+
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+
+@mcp.resource("greeting://{name}")
+def get_greeting(name: str) -> str:
+    """Get a personalized greeting"""
+    return f"Hello, {name}!"
+
+
+@mcp.prompt()
+def greet_user(name: str, style: str = "friendly") -> str:
+    """Generate a greeting prompt"""
+    return f"Write a {style} greeting for someone named {name}."
+```
+
+Test it with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+
+```bash
+uv run mcp dev server.py
+```
+
+## Getting Started
+
+<!-- TODO(Marcelo): automatically generate the follow references with a header on each of those files. -->
+1. **[Install](installation.md)** the MCP SDK
+2. **[Learn concepts](concepts.md)** - understand the three primitives and architecture
+3. **[Explore authorization](authorization.md)** - add security to your servers
+4. **[Use low-level APIs](low-level-server.md)** - for advanced customization
+
+## API Reference
+
+Full API documentation is available in the [API Reference](api.md).

docs/installation.md

@@ -0,0 +1,31 @@
+# Installation
+
+The Python SDK is available on PyPI as [`mcp`](https://pypi.org/project/mcp/) so installation is as simple as:
+
+=== "pip"
+
+    ```bash
+    pip install mcp
+    ```
+=== "uv"
+
+    ```bash
+    uv add mcp
+    ```
+
+The following dependencies are automatically installed:
+
+- [`httpx`](https://pypi.org/project/httpx/): HTTP client to handle HTTP Streamable and SSE transports.
+- [`httpx-sse`](https://pypi.org/project/httpx-sse/): HTTP client to handle SSE transport.
+- [`pydantic`](https://pypi.org/project/pydantic/): Types, JSON schema generation, data validation, and [more](https://docs.pydantic.dev/latest/).
+- [`starlette`](https://pypi.org/project/starlette/): Web framework used to build the HTTP transport endpoints.
+- [`python-multipart`](https://pypi.org/project/python-multipart/): Handle HTTP body parsing.
+- [`sse-starlette`](https://pypi.org/project/sse-starlette/): Server-Sent Events for Starlette, used to build the SSE transport endpoint.
+- [`pydantic-settings`](https://pypi.org/project/pydantic-settings/): Settings management used in FastMCP.
+- [`uvicorn`](https://pypi.org/project/uvicorn/): ASGI server used to run the HTTP transport endpoints.
+- [`jsonschema`](https://pypi.org/project/jsonschema/): JSON schema validation.
+- [`pywin32`](https://pypi.org/project/pywin32/): Windows specific dependencies for the CLI tools.
+
+This package has the following optional groups:
+
+- `cli`: Installs `typer` and `python-dotenv` for the MCP CLI tools.

docs/low-level-server.md

@@ -0,0 +1,5 @@
+# Low-Level Server
+
+!!! warning "Under Construction"
+
+    This page is currently being written. Check back soon for complete documentation.

mkdocs.yml

@@ -11,7 +11,12 @@ site_url: https://modelcontextprotocol.github.io/python-sdk
 # copyright: © Model Context Protocol 2025 to present
 
 nav:
-  - Home: index.md
+  - Introduction: index.md
+  - Installation: installation.md
+  - Documentation:
+      - Concepts: concepts.md
+      - Low-Level Server: low-level-server.md
+      - Authorization: authorization.md
   - API Reference: api.md
 
 theme: