Skip to content

Add stateless mode support for STDIO transport #928

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.

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

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

efj-amzn
Copy link

Motivation and Context

This change adds support for the stateless flag to STDIO transport, addressing issue #912. Currently, STDIO transport requires a full initialization handshake, making simple command line interactions like echo '{"jsonrpc":"2.0",...}' | python script.py impossible.

The stateless flag already exists for HTTP transport but was missing for STDIO. This feature is particularly helpful for:

  • Simple CLI debugging and testing
  • Support for older MCP clients that don't do the handshake
  • Educational scenarios where users are learning about MCP without needing to understand the initialization protocol
  • Quick command-line tool interactions

How Has This Been Tested?

Aside from the added tests, I created a basic server and ran some commands.

from mcp.server.fastmcp import FastMCP

# Create FastMCP server
mcp = FastMCP("StatelessTest")

# Register a simple echo tool
@mcp.tool()
def echo(message: str) -> str:
    """Echo a message back to the client."""
    return f"Echo: {message}"

if __name__ == "__main__":
    # Run in STDIO mode
    mcp.run()
% echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"echo","arguments":{"message":"Hello world"}}}' | FASTMCP_STATELESS_STDIO=true uv run test_stateless.py
[06/10/25 14:52:17] INFO     Processing request of type CallToolRequest                                                                                                                                                                                                                                                                          server.py:561
{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"Echo: Hello world"}],"isError":false}}

% echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"echo","arguments":{"message":"Hello world"}}}' | FASTMCP_STATELESS_STDIO=false uv run test_stateless.py
<runtime exception>

Breaking Changes

None.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

I forked from gitish 1a9ead0 and the tests occasionally hang on that commit.

Fixes #912

efj-amzn added 3 commits June 10, 2025 13:42
This commit implements support for the 'stateless' flag in STDIO transport, addressing issue modelcontextprotocol#912.
The changes include:

- Adding a 'stateless_stdio' flag to FastMCP settings
- Passing this flag to ServerSession when creating STDIO connections
- Adding tests to verify stateless mode works correctly
- Ensuring proper resource cleanup in tests

This enables simpler CLI interaction patterns such as:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call",...}' | python script.py

Without requiring initialization messages, which is helpful for educational purposes
and testing tools quickly via command line.

Fixes modelcontextprotocol#912
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Support the stateless flag for STDIO transport
1 participant