Configuration Guide
Relevant source files
The following files were used as context for generating this wiki page: - [mkdocs.yml](https://github.com/Derek7552/python-sdk/blob/HEAD/mkdocs.yml) - [CLAUDE.md](https://github.com/Derek7552/python-sdk/blob/HEAD/CLAUDE.md) - [CONTRIBUTING.md](https://github.com/Derek7552/python-sdk/blob/HEAD/CONTRIBUTING.md) - [examples/servers/simple-auth/README.md](https://github.com/Derek7552/python-sdk/blob/HEAD/examples/servers/simple-auth/README.md) - [examples/clients/simple-auth-client/README.md](https://github.com/Derek7552/python-sdk/blob/HEAD/examples/clients/simple-auth-client/README.md) - [tests/server/fastmcp/test_server.py](https://github.com/Derek7552/python-sdk/blob/HEAD/tests/server/fastmcp/test_server.py) - [tests/server/fastmcp/auth/test_auth_integration.py](https://github.com/Derek7552/python-sdk/blob/HEAD/tests/server/fastmcp/auth/test_auth_integration.py) - [tests/shared/test_streamable_http.py](https://github.com/Derek7552/python-sdk/blob/HEAD/tests/shared/test_streamable_http.py)This guide provides a comprehensive overview of the configuration options available within the MCP Python SDK project. It covers server-side settings for transports and authentication, client-side connection parameters, documentation site generation, and the development environment setup. Understanding these configurations is essential for both deploying and contributing to the project.
The configuration is managed through a combination of command-line arguments, environment variables, Python class settings, and dedicated configuration files like mkdocs.yml. This multi-faceted approach allows for flexibility in different environments, from local development to production deployment.
Server Configuration
MCP servers, particularly those built with FastMCP, can be configured in several ways, including transport protocols, security settings, and authentication mechanisms.
Transport and Endpoints
The server can be configured to use different transport protocols, such as Server-Sent Events (SSE) or Streamable HTTP. The transport and its associated endpoints can be set programmatically or via command-line arguments.
The following diagram illustrates the server startup and transport selection process.
The FastMCP class has settings to control URL paths. For instance, settings.mount_path can be used to prefix application routes.
Sources: tests/server/fastmcp/test_server.py:60-65
Example servers demonstrate configuration via command-line arguments:
| Argument | Description | Example |
|---|---|---|
--port | Sets the server's listening port. | uv run ... --port=8001 |
--transport | Specifies the transport protocol. | uv run ... --transport=streamable-http |
--auth-server | URL of the separate Authorization Server. | uv run ... --auth-server=http://localhost:9000 |
--oauth-strict | Enables strict RFC 8707 resource validation. | uv run ... --oauth-strict |
Sources: examples/servers/simple-auth/README.md:21-27
Security Settings
The StreamableHTTPSessionManager utilizes a TransportSecuritySettings class to configure security aspects like allowed hosts and origins. This is crucial for preventing common web security vulnerabilities.
| Setting | Type | Description |
|---|---|---|
allowed_hosts | list[str] | A list of allowed host headers. |
allowed_origins | list[str] | A list of allowed origins for CORS. |
Sources: tests/shared/test_streamable_http.py:177-180
OAuth Authentication Configuration
The SDK supports OAuth 2.0 and separates the roles of Authorization Server (AS) and Resource Server (RS) to comply with RFC 9728. The authentication routes are highly configurable.
The create_auth_routes function is used to set up the OAuth endpoints, taking an OAuthAuthorizationServerProvider and configuration options as arguments.
Sources: tests/server/fastmcp/auth/test_auth_integration.py:228-239
The following diagram shows the sequence for client registration and authorization.
Client Registration and Revocation
Client registration and token revocation can be enabled and configured using ClientRegistrationOptions and RevocationOptions.
ClientRegistrationOptions
| Parameter | Type | Description |
|---|---|---|
enabled | bool | Enables or disables the /register endpoint. |
valid_scopes | list[str] | A list of all scopes the server allows clients to request. |
default_scopes | list[str] | Scopes assigned to a client if none are requested during registration. |
Sources: tests/server/fastmcp/auth/test_auth_integration.py:233-237
RevocationOptions
| Parameter | Type | Description |
|---|---|---|
enabled | bool | Enables or disables the /revoke endpoint for token revocation. |
Sources: tests/server/fastmcp/auth/test_auth_integration.py:238-239
Client Configuration
Clients are typically configured using environment variables, which specify the server to connect to and the transport protocol to use.
| Environment Variable | Description | Default |
|---|---|---|
MCP_SERVER_PORT | The port of the MCP server. | 8000 |
MCP_TRANSPORT_TYPE | The transport protocol to use. Can be streamable_http or sse. | streamable_http |
Sources: examples/clients/simple-auth-client/README.md:47-48
This diagram shows how a client uses these variables to establish a session.
Documentation Site Configuration
The project uses MkDocs with the Material theme to generate its documentation site. The configuration is managed in the mkdocs.yml file.
Key configuration sections in mkdocs.yml:
| Key | Description |
|---|---|
site_name | The name of the documentation site. |
repo_url | The URL of the source code repository, displayed in the header. |
nav | Defines the navigation structure of the site. |
theme | Specifies the theme and its features (e.g., palette, logo). |
markdown_extensions | Enables various Markdown extensions for enhanced rendering, such as pymdownx.superfences for Mermaid diagrams. |
plugins | Configures MkDocs plugins, notably mkdocstrings for automatically generating API reference documentation from source code docstrings. |
Sources: mkdocs.yml
The mkdocstrings plugin is configured to watch the src/mcp directory and generate API documentation from the Python files within it.
Sources: mkdocs.yml:68-81
Development Environment Configuration
The project enforces a strict and consistent development environment through a set of specified tools and practices.
Tooling and Package Management
- Package Manager:
uvis the only permitted package manager.pipis forbidden. - Installation: Dependencies are installed with
uv sync --frozen --all-extras --dev. - Code Formatting:
ruff formatis used for code formatting. - Linting:
ruff checkis used for linting. - Type Checking:
pyrightis used for static type analysis. - Pre-commit Hooks: Pre-commit hooks are set up to automatically run formatters and linters on every commit.
Sources: CLAUDE.md:7-30, CONTRIBUTING.md:14-21
The development workflow, enforced by pre-commit hooks, ensures code quality before it is committed.
Sources: CLAUDE.md:58-62
Conclusion
Configuration in the MCP Python SDK is a layered system that addresses the needs of different roles, from application developers using the SDK to contributors working on the SDK itself. Server and client configurations provide the flexibility needed for various deployment scenarios, including robust security and authentication. The documentation and development environment configurations ensure consistency, quality, and ease of contribution across the project.