Module `fastmcp_extensions.server_config`

MCP Server configuration classes and resolution logic.

This module provides configuration classes for MCP servers, including credential resolution from HTTP headers and environment variables.

Key Components

MCPServerConfigArg: Dataclass for defining credential resolution configuration
MCPServerConfig: Dataclass storing server configuration (attached to the app)
get_mcp_config(): Helper function to get credentials at runtime

Functions

def get_mcp_config(ctx_or_app: Context | FastMCP, name: str) ‑> str

Expand source code

def get_mcp_config(ctx_or_app: Context | FastMCP, name: str) -> str:
    """Get a configuration value from an MCP server.

    This is a convenience function to get config values from a FastMCP
    app created with mcp_server(). It accepts either a Context object (preferred
    for use in MCP tools) or a FastMCP app instance directly.

    When using Context, the function accesses the app via ctx.fastmcp, which
    ensures session-aware resolution of HTTP headers.

    Args:
        ctx_or_app: Either a FastMCP Context object (from tool/resource functions)
            or a FastMCP application instance (created with mcp_server()).
        name: The name of the config argument to get.

    Returns:
        The resolved value as a string.

    Raises:
        AttributeError: If the app was not created with mcp_server().
        KeyError: If the config argument name is not registered.
        ValueError: If the config is required but no value can be resolved.

    Example:
        ```python
        @mcp_tool(...)
        def my_tool(ctx: Context, ...) -> str:
            api_key = get_mcp_config(ctx, "api_key")
            ...
        ```
    """
    # Extract the FastMCP app from Context if needed
    app = ctx_or_app.fastmcp if isinstance(ctx_or_app, Context) else ctx_or_app

    config: MCPServerConfig = app.x_mcp_server_config  # type: ignore[attr-defined]
    return config.get_config(name)

Get a configuration value from an MCP server.

This is a convenience function to get config values from a FastMCP app created with mcp_server(). It accepts either a Context object (preferred for use in MCP tools) or a FastMCP app instance directly.

When using Context, the function accesses the app via ctx.fastmcp, which ensures session-aware resolution of HTTP headers.

Args

ctx_or_app: Either a FastMCP Context object (from tool/resource functions) or a FastMCP application instance (created with mcp_server()).
name: The name of the config argument to get.

Returns

The resolved value as a string.

Raises

AttributeError: If the app was not created with mcp_server().
KeyError: If the config argument name is not registered.
ValueError: If the config is required but no value can be resolved.

Example

@mcp_tool(...)
def my_tool(ctx: Context, ...) -> str:
    api_key = get_mcp_config(ctx, "api_key")
    ...

Classes

class MCPServerConfig (name: str, package_name: str | None = None, advertised_properties: dict[str, Any] = <factory>, config_args: list[MCPServerConfigArg] = <factory>)

Expand source code

@dataclass
class MCPServerConfig:
    """Configuration for an MCP server created via mcp_server().

    This class stores the configuration passed to mcp_server() and provides
    methods for credential resolution.
    """

    name: str
    package_name: str | None = None
    advertised_properties: dict[str, Any] = field(default_factory=dict)
    config_args: list[MCPServerConfigArg] = field(default_factory=list)
    _config_args_by_name: dict[str, MCPServerConfigArg] = field(
        default_factory=dict, init=False, repr=False
    )

    def __post_init__(self) -> None:
        """Build lookup dict for config args by name."""
        self._config_args_by_name = {arg.name: arg for arg in self.config_args}

    def get_config(self, name: str) -> str:
        """Get a configuration value by name.

        Resolution order:
        1. HTTP headers (case-insensitive)
        2. Environment variables
        3. Default value

        Args:
            name: The name of the config argument to get.

        Returns:
            The resolved value as a string.

        Raises:
            KeyError: If the config argument name is not registered.
            ValueError: If the config is required but no value can be resolved.
        """
        if name not in self._config_args_by_name:
            raise KeyError(f"Unknown config argument: {name}")

        config_arg = self._config_args_by_name[name]
        return _resolve_config_arg(config_arg)

Configuration for an MCP server created via mcp_server().

This class stores the configuration passed to mcp_server() and provides methods for credential resolution.

Instance variables

var advertised_properties : dict[str, typing.Any]
var config_args : list[MCPServerConfigArg]
var name : str
var package_name : str | None

Methods

def get_config(self, name: str) ‑> str

Expand source code

def get_config(self, name: str) -> str:
    """Get a configuration value by name.

    Resolution order:
    1. HTTP headers (case-insensitive)
    2. Environment variables
    3. Default value

    Args:
        name: The name of the config argument to get.

    Returns:
        The resolved value as a string.

    Raises:
        KeyError: If the config argument name is not registered.
        ValueError: If the config is required but no value can be resolved.
    """
    if name not in self._config_args_by_name:
        raise KeyError(f"Unknown config argument: {name}")

    config_arg = self._config_args_by_name[name]
    return _resolve_config_arg(config_arg)

Get a configuration value by name.

Resolution order: 1. HTTP headers (case-insensitive) 2. Environment variables 3. Default value

Args

name: The name of the config argument to get.

Returns

The resolved value as a string.

Raises

KeyError: If the config argument name is not registered.
ValueError: If the config is required but no value can be resolved.

Expand source code

@dataclass
class MCPServerConfigArg:
    """Configuration argument for MCP server credential resolution.

    This class defines a configuration argument that can be resolved from
    HTTP headers or environment variables, with support for sensitive values.

    Attributes:
        name: Unique name for this config argument (used for resolution).
        http_header_key: HTTP header name to check first (case-insensitive). Optional.
        env_var: Environment variable name to check as fallback. Optional.
        default: Default value if not found. Can be a string or a callable returning a string.
        required: If True, resolution will raise an error if not found (after checking default).
        sensitive: If True, the value will be masked in logs/output.
        normalize_fn: Optional function to transform the resolved value. Useful for
            parsing values like "Bearer <token>" from Authorization headers.
            The function receives the raw value and returns the normalized value,
            or None if the value should be treated as not found (triggering fallback).
            The function may also raise an exception for invalid input validation.
            When raising exceptions, avoid including the raw value in error messages
            as it may contain sensitive credentials.
    """

    name: str
    http_header_key: str | None = None
    env_var: str | None = None
    default: str | Callable[[], str] | None = None
    required: bool = True
    sensitive: bool = False
    normalize_fn: Callable[[str], str | None] | None = None

Configuration argument for MCP server credential resolution.

This class defines a configuration argument that can be resolved from HTTP headers or environment variables, with support for sensitive values.

Attributes

name: Unique name for this config argument (used for resolution).
http_header_key: HTTP header name to check first (case-insensitive). Optional.
env_var: Environment variable name to check as fallback. Optional.
default: Default value if not found. Can be a string or a callable returning a string.
required: If True, resolution will raise an error if not found (after checking default).
sensitive: If True, the value will be masked in logs/output.
normalize_fn: Optional function to transform the resolved value. Useful for parsing values like "Bearer " from Authorization headers. The function receives the raw value and returns the normalized value, or None if the value should be treated as not found (triggering fallback). The function may also raise an exception for invalid input validation. When raising exceptions, avoid including the raw value in error messages as it may contain sensitive credentials.

Instance variables

var default : str | collections.abc.Callable[[], str] | None
var env_var : str | None
var http_header_key : str | None
var name : str
var normalize_fn : collections.abc.Callable[[str], str | None] | None
var required : bool
var sensitive : bool