added type validation for optional params

Author: Agasthya Kasturi

README.md

@@ -66,7 +66,7 @@ The Model Context Protocol allows applications to provide context for LLMs in a
 
 - Build MCP clients that can connect to any MCP server
 - Create MCP servers that expose resources, prompts and tools
-- Use standard transports like stdio and SSE
+- Use standard transports like stdio, SSE, and Streamable HTTP
 - Handle all MCP protocol messages and lifecycle events
 
 ## Installation
@@ -160,7 +160,7 @@ from dataclasses import dataclass
 
 from fake_database import Database  # Replace with your actual DB type
 
-from mcp.server.fastmcp import Context, FastMCP
+from mcp.server.fastmcp import FastMCP
 
 # Create a named server
 mcp = FastMCP("My App")
@@ -192,8 +192,9 @@ mcp = FastMCP("My App", lifespan=app_lifespan)
 
 # Access type-safe lifespan context in tools
 @mcp.tool()
-def query_db(ctx: Context) -> str:
+def query_db() -> str:
     """Tool that uses initialized resources"""
+    ctx = mcp.get_context()
     db = ctx.request_context.lifespan_context["db"]
     return db.query()
 ```
@@ -218,6 +219,15 @@ def get_config() -> str:
 def get_user_profile(user_id: str) -> str:
     """Dynamic user data"""
     return f"Profile data for user {user_id}"
+
+
+# Example with form-style query expansion (RFC 6570) using multiple parameters
+@mcp.resource("articles://{article_id}/view{?format,lang}")
+def view_article(article_id: str, format: str = "html", lang: str = "english") -> str:
+    """View an article, with optional format and language selection.
+    Example URI: articles://123/view?format=pdf&lang=english"""
+    content = f"Content for article {article_id} in {format} format Viewing in {lang}."
+    return content
 ```
 
 ### Tools
@@ -309,6 +319,33 @@ async def long_task(files: list[str], ctx: Context) -> str:
     return "Processing complete"
 ```
 
+### Authentication
+
+Authentication can be used by servers that want to expose tools accessing protected resources.
+
+`mcp.server.auth` implements an OAuth 2.0 server interface, which servers can use by
+providing an implementation of the `OAuthServerProvider` protocol.
+
+```
+mcp = FastMCP("My App",
+        auth_server_provider=MyOAuthServerProvider(),
+        auth=AuthSettings(
+            issuer_url="https://myapp.com",
+            revocation_options=RevocationOptions(
+                enabled=True,
+            ),
+            client_registration_options=ClientRegistrationOptions(
+                enabled=True,
+                valid_scopes=["myscope", "myotherscope"],
+                default_scopes=["myscope"],
+            ),
+            required_scopes=["myscope"],
+        ),
+)
+```
+
+See [OAuthServerProvider](src/mcp/server/auth/provider.py) for more details.
+
 ## Running Your Server
 
 ### Development Mode
@@ -360,8 +397,95 @@ python server.py
 mcp run server.py
 ```
 
+Note that `mcp run` or `mcp dev` only supports server using FastMCP and not the low-level server variant.
+
+### Streamable HTTP Transport
+
+> **Note**: Streamable HTTP transport is superseding SSE transport for production deployments.
+
+```python
+from mcp.server.fastmcp import FastMCP
+
+# Stateful server (maintains session state)
+mcp = FastMCP("StatefulServer")
+
+# Stateless server (no session persistence)
+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)
+
+# Run server with streamable_http transport
+mcp.run(transport="streamable-http")
+```
+
+You can mount multiple FastMCP servers in a FastAPI application:
+
+```python
+# echo.py
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP(name="EchoServer", stateless_http=True)
+
+
+@mcp.tool(description="A simple echo tool")
+def echo(message: str) -> str:
+    return f"Echo: {message}"
+```
+
+```python
+# math.py
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP(name="MathServer", stateless_http=True)
+
+
+@mcp.tool(description="A simple add tool")
+def add_two(n: int) -> int:
+    return n + 2
+```
+
+```python
+# main.py
+import contextlib
+from fastapi import FastAPI
+from mcp.echo import echo
+from mcp.math import math
+
+
+# Create a combined lifespan to manage both session managers
+@contextlib.asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with contextlib.AsyncExitStack() as stack:
+        await stack.enter_async_context(echo.mcp.session_manager.run())
+        await stack.enter_async_context(math.mcp.session_manager.run())
+        yield
+
+
+app = FastAPI(lifespan=lifespan)
+app.mount("/echo", echo.mcp.streamable_http_app())
+app.mount("/math", math.mcp.streamable_http_app())
+```
+
+For low level server with Streamable HTTP implementations, see:
+- Stateful server: [`examples/servers/simple-streamablehttp/`](examples/servers/simple-streamablehttp/)
+- Stateless server: [`examples/servers/simple-streamablehttp-stateless/`](examples/servers/simple-streamablehttp-stateless/)
+
+
+
+The streamable HTTP transport supports:
+- Stateful and stateless operation modes
+- Resumability with event stores
+- JSON or SSE response formats  
+- Better scalability for multi-node deployments
+
+
 ### Mounting to an Existing ASGI Server
 
+> **Note**: SSE transport is being superseded by [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).
+
+By default, SSE servers are mounted at `/sse` and Streamable HTTP servers are mounted at `/mcp`. You can customize these paths using the methods described below.
+
 You can mount the SSE server to an existing ASGI server using the `sse_app` method. This allows you to integrate the SSE server with other ASGI applications.
 
 ```python
@@ -383,6 +507,43 @@ app = Starlette(
 app.router.routes.append(Host('mcp.acme.corp', app=mcp.sse_app()))
 ```
 
+When mounting multiple MCP servers under different paths, you can configure the mount path in several ways:
+
+```python
+from starlette.applications import Starlette
+from starlette.routing import Mount
+from mcp.server.fastmcp import FastMCP
+
+# Create multiple MCP servers
+github_mcp = FastMCP("GitHub API")
+browser_mcp = FastMCP("Browser")
+curl_mcp = FastMCP("Curl")
+search_mcp = FastMCP("Search")
+
+# Method 1: Configure mount paths via settings (recommended for persistent configuration)
+github_mcp.settings.mount_path = "/github"
+browser_mcp.settings.mount_path = "/browser"
+
+# Method 2: Pass mount path directly to sse_app (preferred for ad-hoc mounting)
+# This approach doesn't modify the server's settings permanently
+
+# Create Starlette app with multiple mounted servers
+app = Starlette(
+    routes=[
+        # Using settings-based configuration
+        Mount("/github", app=github_mcp.sse_app()),
+        Mount("/browser", app=browser_mcp.sse_app()),
+        # Using direct mount path parameter
+        Mount("/curl", app=curl_mcp.sse_app("/curl")),
+        Mount("/search", app=search_mcp.sse_app("/search")),
+    ]
+)
+
+# Method 3: For direct execution, you can also pass the mount path to run()
+if __name__ == "__main__":
+    search_mcp.run(transport="sse", mount_path="/search")
+```
+
 For more information on mounting applications in Starlette, see the [Starlette documentation](https://www.starlette.io/routing/#submounting-routes).
 
 ## Examples
@@ -403,6 +564,23 @@ def echo_resource(message: str) -> str:
     return f"Resource echo: {message}"
 
 
+# Example with form-style query expansion for customizing echo output
+@mcp.resource("echo://custom/{message}{?case,reverse}")
+def custom_echo_resource(
+    message: str, case: str = "lower", reverse: bool = False
+) -> str:
+    """Echo a message with optional case transformation and reversal.
+    Example URI: echo://custom/Hello?case=upper&reverse=true"""
+    processed_message = message
+    if case == "upper":
+        processed_message = processed_message.upper()
+    elif case == "lower":
+        processed_message = processed_message.lower()
+    if reverse:
+        processed_message = processed_message[::-1]
+    return f"Custom resource echo: {processed_message}"
+
+
 @mcp.tool()
 def echo_tool(message: str) -> str:
     """Echo a message as a tool"""
@@ -435,6 +613,34 @@ def get_schema() -> str:
     return "\n".join(sql[0] for sql in schema if sql[0])
 
 
+# Example with form-style query expansion for table-specific schema
+@mcp.resource("schema://{table_name}{?include_indexes}")
+def get_table_schema(table_name: str, include_indexes: bool = False) -> str:
+    """Provide the schema for a specific table, optionally including indexes.
+    Example URI: schema://users?include_indexes=true"""
+    conn = sqlite3.connect("database.db")
+    cursor = conn.cursor()
+    try:
+        base_query = "SELECT sql FROM sqlite_master WHERE type='table' AND name=?"
+        params: list[str] = [table_name]
+        if include_indexes:
+            cursor.execute(base_query, params)
+            schema_parts = cursor.fetchall()
+
+            index_query = (
+                "SELECT sql FROM sqlite_master WHERE type='index' AND tbl_name=?"
+            )
+            cursor.execute(index_query, params)
+            schema_parts.extend(cursor.fetchall())
+        else:
+            cursor.execute(base_query, params)
+            schema_parts = cursor.fetchall()
+
+        return "\n".join(sql[0] for sql in schema_parts if sql and sql[0])
+    finally:
+        conn.close()
+
+
 @mcp.tool()
 def query_data(sql: str) -> str:
     """Execute SQL queries safely"""
@@ -555,9 +761,11 @@ if __name__ == "__main__":
     asyncio.run(run())
 ```
 
+Caution: The `mcp run` and `mcp dev` tool doesn't support low-level server.
+
 ### Writing MCP Clients
 
-The SDK provides a high-level client interface for connecting to MCP servers:
+The SDK provides a high-level client interface for connecting to MCP servers using various [transports](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports):
 
 ```python
 from mcp import ClientSession, StdioServerParameters, types
@@ -621,6 +829,82 @@ if __name__ == "__main__":
     asyncio.run(run())
 ```
 
+Clients can also connect using [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http):
+
+```python
+from mcp.client.streamable_http import streamablehttp_client
+from mcp import ClientSession
+
+
+async def main():
+    # Connect to a streamable HTTP server
+    async with streamablehttp_client("example/mcp") as (
+        read_stream,
+        write_stream,
+        _,
+    ):
+        # Create a session using the client streams
+        async with ClientSession(read_stream, write_stream) as session:
+            # Initialize the connection
+            await session.initialize()
+            # Call a tool
+            tool_result = await session.call_tool("echo", {"message": "hello"})
+```
+
+### OAuth Authentication for Clients
+
+The SDK includes [authorization support](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) for connecting to protected MCP servers:
+
+```python
+from mcp.client.auth import OAuthClientProvider, TokenStorage
+from mcp.client.session import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
+
+
+class CustomTokenStorage(TokenStorage):
+    """Simple in-memory token storage implementation."""
+
+    async def get_tokens(self) -> OAuthToken | None:
+        pass
+
+    async def set_tokens(self, tokens: OAuthToken) -> None:
+        pass
+
+    async def get_client_info(self) -> OAuthClientInformationFull | None:
+        pass
+
+    async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
+        pass
+
+
+async def main():
+    # Set up OAuth authentication
+    oauth_auth = OAuthClientProvider(
+        server_url="https://api.example.com",
+        client_metadata=OAuthClientMetadata(
+            client_name="My Client",
+            redirect_uris=["http://localhost:3000/callback"],
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+        ),
+        storage=CustomTokenStorage(),
+        redirect_handler=lambda url: print(f"Visit: {url}"),
+        callback_handler=lambda: ("auth_code", None),
+    )
+
+    # Use with streamable HTTP client
+    async with streamablehttp_client(
+        "https://api.example.com/mcp", auth=oauth_auth
+    ) as (read, write, _):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            # Authenticated session ready
+```
+
+For a complete working example, see [`examples/clients/simple-auth-client/`](examples/clients/simple-auth-client/).
+
+
 ### MCP Primitives
 
 The MCP protocol defines three core primitives that servers can implement:
@@ -655,4 +939,4 @@ We are passionate about supporting contributors of all levels of experience and
 
 ## License
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+This project is licensed under the MIT License - see the LICENSE file for details.