FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

docs: Update examples to use stateless HTTP with JSON responses by domdomegg · Pull Request #1499 · modelcontextprotocol/python-sdk · GitHub

/ python-sdk Public

docs: Update examples to use stateless HTTP with JSON responses #1499

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
felixweinberger merged 4 commits into from
Nov 20, 2025
Conversation 2 Commits 4 Checks 21 Files changed
Merged

docs: Update examples to use stateless HTTP with JSON responses #1499

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b5327f4
docs: Update examples to use stateless HTTP with JSON responses
domdomegg Oct 20, 2025
2b4552f
docs: Update index.md example to use stateless HTTP with JSON
domdomegg Oct 20, 2025
cbfb9d8
docs: Update quickstart instructions for testing with inspector
domdomegg Oct 20, 2025
8dbdfb2
Address feedback: remove stateless_http from examples, keep json_resp…
domdomegg Nov 18, 2025
File filter

Filter by extension

Filter by extension .md  (2) .py  (8) All 2 file types selected
Viewed files
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Unified
Split
Hide whitespace
Diff view
Unified
Split
Hide whitespace
58 changes: 38 additions & 20 deletions README.md
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -132,14 +132,14 @@ Let's create a simple MCP server that exposes a calculator tool and some data:
"""
FastMCP quickstart example.

cd to the `examples/snippets/clients` directory and run:
uv run server fastmcp_quickstart stdio
Run from the repository root:
uv run examples/snippets/servers/fastmcp_quickstart.py
"""

from mcp.server.fastmcp import FastMCP

# Create an MCP server
mcp = FastMCP("Demo")
mcp = FastMCP("Demo", json_response=True)


# Add an addition tool
Expand Down Expand Up @@ -167,23 +167,36 @@ def greet_user(name: str, style: str = "friendly") -> str:
}

return f"{styles.get(style, styles['friendly'])} for someone named {name}."


# Run with streamable HTTP transport
if __name__ == "__main__":
mcp.run(transport="streamable-http")
```

_Full example: [examples/snippets/servers/fastmcp_quickstart.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/fastmcp_quickstart.py)_
<!-- /snippet-source -->

You can install this server in [Claude Desktop](https://claude.ai/download) and interact with it right away by running:
You can install this server in [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp) and interact with it right away. First, run the server:

```bash
uv run mcp install server.py
uv run --with mcp examples/snippets/servers/fastmcp_quickstart.py
```

Alternatively, you can test it with the MCP Inspector:
Then add it to Claude Code:

```bash
uv run mcp dev server.py
claude mcp add --transport http my-server http://localhost:8000/mcp
```

Alternatively, you can test it with the MCP Inspector. Start the server as above, then in a separate terminal:

```bash
npx -y @modelcontextprotocol/inspector
```

In the inspector UI, connect to `http://localhost:8000/mcp`.

## What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but specifically designed for LLM interactions. MCP servers can:
Expand Down Expand Up @@ -888,6 +901,7 @@ class SimpleTokenVerifier(TokenVerifier):
# Create FastMCP instance as a Resource Server
mcp = FastMCP(
"Weather Service",
json_response=True,
# Token verifier for authentication
token_verifier=SimpleTokenVerifier(),
# Auth settings for RFC 9728 Protected Resource Metadata
Expand Down Expand Up @@ -1103,7 +1117,7 @@ Note that `uv run mcp run` or `uv run mcp dev` only supports server using FastMC

### Streamable HTTP Transport

> **Note**: Streamable HTTP transport is superseding SSE transport for production deployments.
> **Note**: Streamable HTTP transport is the recommended transport for production deployments. Use `stateless_http=True` and `json_response=True` for optimal scalability.

<!-- snippet-source examples/snippets/servers/streamable_config.py -->
```python
Expand All @@ -1114,15 +1128,15 @@ Run from the repository root:

from mcp.server.fastmcp import FastMCP

# Stateful server (maintains session state)
mcp = FastMCP("StatefulServer")
# Stateless server with JSON responses (recommended)
mcp = FastMCP("StatelessServer", stateless_http=True, json_response=True)

# Other configuration options:
# Stateless server (no session persistence)
# Stateless server with SSE streaming responses
# mcp = FastMCP("StatelessServer", stateless_http=True)

# Stateless server (no session persistence, no sse stream with supported client)
# mcp = FastMCP("StatelessServer", stateless_http=True, json_response=True)
# Stateful server with session persistence
# mcp = FastMCP("StatefulServer")


# Add a simple tool to demonstrate the server
Expand Down Expand Up @@ -1157,7 +1171,7 @@ from starlette.routing import Mount
from mcp.server.fastmcp import FastMCP

# Create the Echo server
echo_mcp = FastMCP(name="EchoServer", stateless_http=True)
echo_mcp = FastMCP(name="EchoServer", stateless_http=True, json_response=True)


@echo_mcp.tool()
Expand All @@ -1167,7 +1181,7 @@ def echo(message: str) -> str:


# Create the Math server
math_mcp = FastMCP(name="MathServer", stateless_http=True)
math_mcp = FastMCP(name="MathServer", stateless_http=True, json_response=True)


@math_mcp.tool()
Expand Down Expand Up @@ -1268,7 +1282,7 @@ from starlette.routing import Mount
from mcp.server.fastmcp import FastMCP

# Create MCP server
mcp = FastMCP("My App")
mcp = FastMCP("My App", json_response=True)


@mcp.tool()
Expand Down Expand Up @@ -1305,7 +1319,7 @@ from starlette.routing import Host
from mcp.server.fastmcp import FastMCP

# Create MCP server
mcp = FastMCP("MCP Host App")
mcp = FastMCP("MCP Host App", json_response=True)


@mcp.tool()
Expand Down Expand Up @@ -1342,8 +1356,8 @@ from starlette.routing import Mount
from mcp.server.fastmcp import FastMCP

# Create multiple MCP servers
api_mcp = FastMCP("API Server")
chat_mcp = FastMCP("Chat Server")
api_mcp = FastMCP("API Server", json_response=True)
chat_mcp = FastMCP("Chat Server", json_response=True)


@api_mcp.tool()
Expand Down Expand Up @@ -1393,7 +1407,11 @@ from mcp.server.fastmcp import FastMCP

# Configure streamable_http_path during initialization
# This server will mount at the root of wherever it's mounted
mcp_at_root = FastMCP("My Server", streamable_http_path="/")
mcp_at_root = FastMCP(
"My Server",
json_response=True,
streamable_http_path="/",
)


@mcp_at_root.tool()
Expand Down
16 changes: 13 additions & 3 deletions docs/index.md
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ 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 = FastMCP("Test Server", json_response=True)


@mcp.tool()
Expand All @@ -36,12 +36,22 @@ def get_greeting(name: str) -> str:
def greet_user(name: str, style: str = "friendly") -> str:
"""Generate a greeting prompt"""
return f"Write a {style} greeting for someone named {name}."


if __name__ == "__main__":
mcp.run(transport="streamable-http")
```

Run the server:

```bash
uv run --with mcp server.py
```

Test it with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
Then open the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) and connect to `http://localhost:8000/mcp`:

```bash
uv run mcp dev server.py
npx -y @modelcontextprotocol/inspector
```

## Getting Started
Expand Down
11 changes: 8 additions & 3 deletions examples/snippets/servers/fastmcp_quickstart.py
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
"""
FastMCP quickstart example.

cd to the `examples/snippets/clients` directory and run:
uv run server fastmcp_quickstart stdio
Run from the repository root:
uv run examples/snippets/servers/fastmcp_quickstart.py
"""

from mcp.server.fastmcp import FastMCP

# Create an MCP server
mcp = FastMCP("Demo")
mcp = FastMCP("Demo", json_response=True)


# Add an addition tool
Expand Down Expand Up @@ -36,3 +36,8 @@ def greet_user(name: str, style: str = "friendly") -> str:
}

return f"{styles.get(style, styles['friendly'])} for someone named {name}."


# Run with streamable HTTP transport
if __name__ == "__main__":
mcp.run(transport="streamable-http")
1 change: 1 addition & 0 deletions examples/snippets/servers/oauth_server.py
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ async def verify_token(self, token: str) -> AccessToken | None:
# Create FastMCP instance as a Resource Server
mcp = FastMCP(
"Weather Service",
json_response=True,
# Token verifier for authentication
token_verifier=SimpleTokenVerifier(),
# Auth settings for RFC 9728 Protected Resource Metadata
Expand Down
10 changes: 5 additions & 5 deletions examples/snippets/servers/streamable_config.py
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,15 @@

from mcp.server.fastmcp import FastMCP

# Stateful server (maintains session state)
mcp = FastMCP("StatefulServer")
# Stateless server with JSON responses (recommended)
mcp = FastMCP("StatelessServer", stateless_http=True, json_response=True)

# Other configuration options:
# Stateless server (no session persistence)
# Stateless server with SSE streaming responses
# mcp = FastMCP("StatelessServer", stateless_http=True)

# Stateless server (no session persistence, no sse stream with supported client)
# mcp = FastMCP("StatelessServer", stateless_http=True, json_response=True)
# Stateful server with session persistence
# mcp = FastMCP("StatefulServer")


# Add a simple tool to demonstrate the server
Expand Down
2 changes: 1 addition & 1 deletion examples/snippets/servers/streamable_http_basic_mounting.py
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
from mcp.server.fastmcp import FastMCP

# Create MCP server
mcp = FastMCP("My App")
mcp = FastMCP("My App", json_response=True)


@mcp.tool()
Expand Down
2 changes: 1 addition & 1 deletion examples/snippets/servers/streamable_http_host_mounting.py
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
from mcp.server.fastmcp import FastMCP

# Create MCP server
mcp = FastMCP("MCP Host App")
mcp = FastMCP("MCP Host App", json_response=True)


@mcp.tool()
Expand Down
4 changes: 2 additions & 2 deletions examples/snippets/servers/streamable_http_multiple_servers.py
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@
from mcp.server.fastmcp import FastMCP

# Create multiple MCP servers
api_mcp = FastMCP("API Server")
chat_mcp = FastMCP("Chat Server")
api_mcp = FastMCP("API Server", json_response=True)
chat_mcp = FastMCP("Chat Server", json_response=True)


@api_mcp.tool()
Expand Down
6 changes: 5 additions & 1 deletion examples/snippets/servers/streamable_http_path_config.py
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,11 @@

# Configure streamable_http_path during initialization
# This server will mount at the root of wherever it's mounted
mcp_at_root = FastMCP("My Server", streamable_http_path="/")
mcp_at_root = FastMCP(
"My Server",
json_response=True,
streamable_http_path="/",
)


@mcp_at_root.tool()
Expand Down
4 changes: 2 additions & 2 deletions examples/snippets/servers/streamable_starlette_mount.py
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
from mcp.server.fastmcp import FastMCP

# Create the Echo server
echo_mcp = FastMCP(name="EchoServer", stateless_http=True)
echo_mcp = FastMCP(name="EchoServer", stateless_http=True, json_response=True)


@echo_mcp.tool()
Expand All @@ -21,7 +21,7 @@ def echo(message: str) -> str:


# Create the Math server
math_mcp = FastMCP(name="MathServer", stateless_http=True)
math_mcp = FastMCP(name="MathServer", stateless_http=True, json_response=True)


@math_mcp.tool()
Expand Down
Loading
Back | FazBrowse Home | New Git URL