From e989e6eeb2315435a1078a43e44df23c27489bbb Mon Sep 17 00:00:00 2001
From: Max Isbey <224885523+maxisbey@users.noreply.github.com>
Date: Sat, 25 Jul 2026 19:28:49 +0000
Subject: [PATCH 1/3] Stop advertising MCP_* env vars for MCPServer settings;
 drop pydantic-settings

The Settings docstring and the installation docs claimed MCPServer could be
configured through MCP_* environment variables and a .env file, but MCPServer
always passes explicit constructor arguments to Settings, and those outrank the
environment in pydantic-settings, so e.g. MCP_DEBUG=true has never taken effect.

Make Settings a plain pydantic BaseModel and remove pydantic-settings from the
runtime dependencies (it moves to the dev group, where the examples still use
it). The migration guide explains how to feed environment variables into the
constructor for anyone who wants that behaviour.
---
 docs/get-started/installation.md   |  1 -
 docs/migration.md                  | 16 ++++++++++++++++
 pyproject.toml                     |  4 +++-
 src/mcp/server/mcpserver/server.py | 18 +++---------------
 uv.lock                            |  4 ++--
 5 files changed, 24 insertions(+), 19 deletions(-)

diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md
index 5113eba269..d39c12e391 100644
--- a/docs/get-started/installation.md
+++ b/docs/get-started/installation.md
@@ -34,7 +34,6 @@ You don't need to know any of this to use the SDK, but if you're wondering what
 * `mcp-types`: every protocol type (requests, results, content blocks) as its own package, versioned in lockstep with the SDK. Every `from mcp_types import ...` in these docs is this package.
 * [`anyio`](https://anyio.readthedocs.io/): the async runtime. The whole SDK is written against anyio, so it runs on either `asyncio` or `trio`.
 * [`pydantic`](https://docs.pydantic.dev/): what every `mcp_types` model is built on, plus all schema generation and validation.
-* [`pydantic-settings`](https://docs.pydantic.dev/latest/concepts/pydantic_settings/): server configuration via `MCP_*` environment variables and `.env` files.
 * [`httpx2`](https://pypi.org/project/httpx2/): the HTTP client behind the Streamable HTTP and SSE *client* transports, with server-sent events support built in.
 * [`starlette`](https://www.starlette.io/), [`uvicorn`](https://www.uvicorn.org/), [`sse-starlette`](https://pypi.org/project/sse-starlette/), and [`python-multipart`](https://pypi.org/project/python-multipart/): the HTTP *server* transports.
 * [`jsonschema`](https://pypi.org/project/jsonschema/): validates a tool's structured output against its declared output schema.
diff --git a/docs/migration.md b/docs/migration.md
index afe0953631..768c4df146 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -684,6 +684,22 @@ app = Starlette(routes=[Mount("/", app=mcp.streamable_http_app(json_response=Tru
 
 If you were mutating these via `mcp.settings` after construction (e.g., `mcp.settings.port = 9000`), pass them to `run()` / `sse_app()` / `streamable_http_app()` instead — these fields no longer exist on `Settings`. The `debug` and `log_level` parameters remain on the constructor.
 
+### `MCP_*` environment variables and `.env` files are no longer read
+
+The `Settings` docstring advertised configuration via `MCP_*` environment variables and a `.env` file (e.g. `MCP_DEBUG=true`), but constructor arguments have always taken precedence, so those environment variables never took effect. `Settings` is now a plain Pydantic model rather than a `pydantic-settings` `BaseSettings`, and `pydantic-settings` is no longer a dependency of the SDK.
+
+If you want environment-driven configuration, read the environment yourself and pass the values to the constructor:
+
+```python
+import os
+
+from mcp.server.mcpserver import MCPServer
+
+mcp = MCPServer("Demo", debug=os.environ.get("MCP_DEBUG") == "true")
+```
+
+If your own code uses `pydantic-settings`, add it to your project's dependencies directly.
+
 ### Streamable HTTP request bodies are limited to 4 MiB
 
 V2 applies a 4 MiB default limit to Streamable HTTP POST bodies and returns HTTP 413 before parsing
diff --git a/pyproject.toml b/pyproject.toml
index cab256720b..5ce8812540 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -58,6 +58,9 @@ dev = [
     # We add mcp[cli] so `uv sync` considers the extras.
     "mcp[cli]",
     "mcp-example-stories",
+    # pydantic-settings is used only by examples (simple-auth, mcpserver/text_me);
+    # keep it reachable for pyright, which covers examples/servers.
+    "pydantic-settings>=2.5.2",
     "tomli>=2.0; python_version < '3.11'",
     "pyright>=1.1.400",
     "pytest>=8.4.0",
@@ -128,7 +131,6 @@ dependencies = [
     "starlette>=0.27; python_version < '3.14'",
     "python-multipart>=0.0.9",
     "sse-starlette>=3.0.0",
-    "pydantic-settings>=2.5.2",
     "uvicorn>=0.31.1; sys_platform != 'emscripten'",
     "jsonschema>=4.20.0",
     "pywin32>=311; sys_platform == 'win32'",
diff --git a/src/mcp/server/mcpserver/server.py b/src/mcp/server/mcpserver/server.py
index c6a75ec925..33a0b08c84 100644
--- a/src/mcp/server/mcpserver/server.py
+++ b/src/mcp/server/mcpserver/server.py
@@ -44,8 +44,8 @@
 from mcp_types import Resource as MCPResource
 from mcp_types import ResourceTemplate as MCPResourceTemplate
 from mcp_types import Tool as MCPTool
+from pydantic import BaseModel
 from pydantic.networks import AnyUrl
-from pydantic_settings import BaseSettings, SettingsConfigDict
 from starlette.applications import Starlette
 from starlette.middleware import Middleware
 from starlette.middleware.authentication import AuthenticationMiddleware
@@ -98,20 +98,8 @@
 _CallableT = TypeVar("_CallableT", bound=Callable[..., Any])
 
 
-class Settings(BaseSettings, Generic[LifespanResultT]):
-    """MCPServer settings.
-
-    All settings can be configured via environment variables with the prefix MCP_.
-    For example, MCP_DEBUG=true will set debug=True.
-    """
-
-    model_config = SettingsConfigDict(
-        env_prefix="MCP_",
-        env_file=".env",
-        env_nested_delimiter="__",
-        nested_model_default_partial_update=True,
-        extra="ignore",
-    )
+class Settings(BaseModel, Generic[LifespanResultT]):
+    """MCPServer settings, as passed to the `MCPServer` constructor."""
 
     # Server settings
     debug: bool
diff --git a/uv.lock b/uv.lock
index 53228bc1a0..b992b278aa 100644
--- a/uv.lock
+++ b/uv.lock
@@ -838,7 +838,6 @@ dependencies = [
     { name = "mcp-types" },
     { name = "opentelemetry-api" },
     { name = "pydantic" },
-    { name = "pydantic-settings" },
     { name = "pyjwt", extra = ["crypto"] },
     { name = "python-multipart" },
     { name = "pywin32", marker = "sys_platform == 'win32'" },
@@ -871,6 +870,7 @@ dev = [
     { name = "mcp-example-stories" },
     { name = "opentelemetry-sdk" },
     { name = "pillow" },
+    { name = "pydantic-settings" },
     { name = "pyright" },
     { name = "pytest" },
     { name = "pytest-examples" },
@@ -899,7 +899,6 @@ requires-dist = [
     { name = "mcp-types", editable = "src/mcp-types" },
     { name = "opentelemetry-api", specifier = ">=1.28.0" },
     { name = "pydantic", specifier = ">=2.12.0" },
-    { name = "pydantic-settings", specifier = ">=2.5.2" },
     { name = "pyjwt", extras = ["crypto"], specifier = ">=2.10.1" },
     { name = "python-dotenv", marker = "extra == 'cli'", specifier = ">=1.0.0" },
     { name = "python-multipart", specifier = ">=0.0.9" },
@@ -926,6 +925,7 @@ dev = [
     { name = "mcp-example-stories", editable = "examples" },
     { name = "opentelemetry-sdk", specifier = ">=1.39.1" },
     { name = "pillow", specifier = ">=12.0" },
+    { name = "pydantic-settings", specifier = ">=2.5.2" },
     { name = "pyright", specifier = ">=1.1.400" },
     { name = "pytest", specifier = ">=8.4.0" },
     { name = "pytest-examples", specifier = ">=0.0.14" },

From c752b0e5459fdd9a338be40caab763cefcf06fd9 Mon Sep 17 00:00:00 2001
From: Max Isbey <224885523+maxisbey@users.noreply.github.com>
Date: Sat, 25 Jul 2026 20:45:34 +0000
Subject: [PATCH 2/3] Remove the examples' pydantic-settings usage instead of
 carrying the dependency

pydantic-settings was left in the dev group only because two examples used it.
The text_me example needs a paid third-party SMS account to run and nothing
references or tests it, so delete it. The simple-auth example's two settings
classes are always constructed with explicit values or defaults, so plain
pydantic models do the same job; drop pydantic-settings from that example's
dependencies and from the root dev group.
---
 examples/mcpserver/text_me.py                 | 67 -------------------
 .../simple-auth/mcp_simple_auth/server.py     |  7 +-
 .../mcp_simple_auth/simple_auth_provider.py   |  7 +-
 examples/servers/simple-auth/pyproject.toml   |  1 -
 pyproject.toml                                |  3 -
 uv.lock                                       | 18 -----
 6 files changed, 4 insertions(+), 99 deletions(-)
 delete mode 100644 examples/mcpserver/text_me.py

diff --git a/examples/mcpserver/text_me.py b/examples/mcpserver/text_me.py
deleted file mode 100644
index f6da331ec4..0000000000
--- a/examples/mcpserver/text_me.py
+++ /dev/null
@@ -1,67 +0,0 @@
-# /// script
-# dependencies = []
-# ///
-
-"""MCPServer Text Me Server
---------------------------------
-This defines a simple MCPServer server that sends a text message to a phone number via https://surgemsg.com/.
-
-To run this example, create a `.env` file with the following values:
-
-SURGE_API_KEY=...
-SURGE_ACCOUNT_ID=...
-SURGE_MY_PHONE_NUMBER=...
-SURGE_MY_FIRST_NAME=...
-SURGE_MY_LAST_NAME=...
-
-Visit https://surgemsg.com/ and click "Get Started" to obtain these values.
-"""
-
-from typing import Annotated
-
-import httpx2
-from pydantic import BeforeValidator
-from pydantic_settings import BaseSettings, SettingsConfigDict
-
-from mcp.server.mcpserver import MCPServer
-
-
-class SurgeSettings(BaseSettings):
-    model_config: SettingsConfigDict = SettingsConfigDict(env_prefix="SURGE_", env_file=".env")
-
-    api_key: str
-    account_id: str
-    my_phone_number: Annotated[str, BeforeValidator(lambda v: "+" + v if not v.startswith("+") else v)]
-    my_first_name: str
-    my_last_name: str
-
-
-# Create server
-mcp = MCPServer("Text me")
-surge_settings = SurgeSettings()  # type: ignore
-
-
-@mcp.tool(name="textme", description="Send a text message to me")
-def text_me(text_content: str) -> str:
-    """Send a text message to a phone number via https://surgemsg.com/"""
-    with httpx2.Client() as client:
-        response = client.post(
-            "https://api.surgemsg.com/messages",
-            headers={
-                "Authorization": f"Bearer {surge_settings.api_key}",
-                "Surge-Account": surge_settings.account_id,
-                "Content-Type": "application/json",
-            },
-            json={
-                "body": text_content,
-                "conversation": {
-                    "contact": {
-                        "first_name": surge_settings.my_first_name,
-                        "last_name": surge_settings.my_last_name,
-                        "phone_number": surge_settings.my_phone_number,
-                    }
-                },
-            },
-        )
-        response.raise_for_status()
-        return f"Message sent: {text_content}"
diff --git a/examples/servers/simple-auth/mcp_simple_auth/server.py b/examples/servers/simple-auth/mcp_simple_auth/server.py
index 0320871b12..89b0744329 100644
--- a/examples/servers/simple-auth/mcp_simple_auth/server.py
+++ b/examples/servers/simple-auth/mcp_simple_auth/server.py
@@ -12,8 +12,7 @@
 from typing import Any, Literal
 
 import click
-from pydantic import AnyHttpUrl
-from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic import AnyHttpUrl, BaseModel
 
 from mcp.server.auth.settings import AuthSettings
 from mcp.server.mcpserver.server import MCPServer
@@ -23,11 +22,9 @@
 logger = logging.getLogger(__name__)
 
 
-class ResourceServerSettings(BaseSettings):
+class ResourceServerSettings(BaseModel):
     """Settings for the MCP Resource Server."""
 
-    model_config = SettingsConfigDict(env_prefix="MCP_RESOURCE_")
-
     # Server settings
     host: str = "localhost"
     port: int = 8001
diff --git a/examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py b/examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py
index 48eb9a8414..5d77ce24b9 100644
--- a/examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py
+++ b/examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py
@@ -12,8 +12,7 @@
 import time
 from typing import Any
 
-from pydantic import AnyHttpUrl
-from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic import AnyHttpUrl, BaseModel
 from starlette.exceptions import HTTPException
 from starlette.requests import Request
 from starlette.responses import HTMLResponse, RedirectResponse, Response
@@ -29,11 +28,9 @@
 from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
 
 
-class SimpleAuthSettings(BaseSettings):
+class SimpleAuthSettings(BaseModel):
     """Simple OAuth settings for demo purposes."""
 
-    model_config = SettingsConfigDict(env_prefix="MCP_")
-
     # Demo user credentials
     demo_username: str = "demo_user"
     demo_password: str = "demo_password"
diff --git a/examples/servers/simple-auth/pyproject.toml b/examples/servers/simple-auth/pyproject.toml
index 455db1e735..89cc163c04 100644
--- a/examples/servers/simple-auth/pyproject.toml
+++ b/examples/servers/simple-auth/pyproject.toml
@@ -12,7 +12,6 @@ dependencies = [
     "httpx2>=2.5.0",
     "mcp",
     "pydantic>=2.0",
-    "pydantic-settings>=2.5.2",
     "sse-starlette>=1.6.1",
     "uvicorn>=0.23.1; sys_platform != 'emscripten'",
 ]
diff --git a/pyproject.toml b/pyproject.toml
index 5ce8812540..c0b1432ef7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -58,9 +58,6 @@ dev = [
     # We add mcp[cli] so `uv sync` considers the extras.
     "mcp[cli]",
     "mcp-example-stories",
-    # pydantic-settings is used only by examples (simple-auth, mcpserver/text_me);
-    # keep it reachable for pyright, which covers examples/servers.
-    "pydantic-settings>=2.5.2",
     "tomli>=2.0; python_version < '3.11'",
     "pyright>=1.1.400",
     "pytest>=8.4.0",
diff --git a/uv.lock b/uv.lock
index b992b278aa..39bb559859 100644
--- a/uv.lock
+++ b/uv.lock
@@ -870,7 +870,6 @@ dev = [
     { name = "mcp-example-stories" },
     { name = "opentelemetry-sdk" },
     { name = "pillow" },
-    { name = "pydantic-settings" },
     { name = "pyright" },
     { name = "pytest" },
     { name = "pytest-examples" },
@@ -925,7 +924,6 @@ dev = [
     { name = "mcp-example-stories", editable = "examples" },
     { name = "opentelemetry-sdk", specifier = ">=1.39.1" },
     { name = "pillow", specifier = ">=12.0" },
-    { name = "pydantic-settings", specifier = ">=2.5.2" },
     { name = "pyright", specifier = ">=1.1.400" },
     { name = "pytest", specifier = ">=8.4.0" },
     { name = "pytest-examples", specifier = ">=0.0.14" },
@@ -1007,7 +1005,6 @@ dependencies = [
     { name = "httpx2" },
     { name = "mcp" },
     { name = "pydantic" },
-    { name = "pydantic-settings" },
     { name = "sse-starlette" },
     { name = "uvicorn", marker = "sys_platform != 'emscripten'" },
 ]
@@ -1026,7 +1023,6 @@ requires-dist = [
     { name = "httpx2", specifier = ">=2.5.0" },
     { name = "mcp" },
     { name = "pydantic", specifier = ">=2.0" },
-    { name = "pydantic-settings", specifier = ">=2.5.2" },
     { name = "sse-starlette", specifier = ">=1.6.1" },
     { name = "uvicorn", marker = "sys_platform != 'emscripten'", specifier = ">=0.23.1" },
 ]
@@ -1935,20 +1931,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/36/c7/cfc8e811f061c841d7990b0201912c3556bfeb99cdcb7ed24adc8d6f8704/pydantic_core-2.41.5-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:56121965f7a4dc965bff783d70b907ddf3d57f6eba29b6d2e5dabfaf07799c51", size = 2145302, upload-time = "2025-11-04T13:43:46.64Z" },
 ]
 
-[[package]]
-name = "pydantic-settings"
-version = "2.10.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "pydantic" },
-    { name = "python-dotenv" },
-    { name = "typing-inspection" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/68/85/1ea668bbab3c50071ca613c6ab30047fb36ab0da1b92fa8f17bbc38fd36c/pydantic_settings-2.10.1.tar.gz", hash = "sha256:06f0062169818d0f5524420a360d632d5857b83cffd4d42fe29597807a1614ee", size = 172583, upload-time = "2025-06-24T13:26:46.841Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/58/f0/427018098906416f580e3cf1366d3b1abfb408a0652e9f31600c24a1903c/pydantic_settings-2.10.1-py3-none-any.whl", hash = "sha256:a60952460b99cf661dc25c29c0ef171721f98bfcb52ef8d9ea4c943d7c8cc796", size = 45235, upload-time = "2025-06-24T13:26:45.485Z" },
-]
-
 [[package]]
 name = "pygments"
 version = "2.20.0"

From 166475c6b05796fc34247b59c8657679a7ab0163 Mon Sep 17 00:00:00 2001
From: Max Isbey <224885523+maxisbey@users.noreply.github.com>
Date: Sat, 25 Jul 2026 21:54:33 +0000
Subject: [PATCH 3/3] Revert "Remove the examples' pydantic-settings usage
 instead of carrying the dependency"

This reverts commit c752b0e5459fdd9a338be40caab763cefcf06fd9.
---
 examples/mcpserver/text_me.py                 | 67 +++++++++++++++++++
 .../simple-auth/mcp_simple_auth/server.py     |  7 +-
 .../mcp_simple_auth/simple_auth_provider.py   |  7 +-
 examples/servers/simple-auth/pyproject.toml   |  1 +
 pyproject.toml                                |  3 +
 uv.lock                                       | 18 +++++
 6 files changed, 99 insertions(+), 4 deletions(-)
 create mode 100644 examples/mcpserver/text_me.py

diff --git a/examples/mcpserver/text_me.py b/examples/mcpserver/text_me.py
new file mode 100644
index 0000000000..f6da331ec4
--- /dev/null
+++ b/examples/mcpserver/text_me.py
@@ -0,0 +1,67 @@
+# /// script
+# dependencies = []
+# ///
+
+"""MCPServer Text Me Server
+--------------------------------
+This defines a simple MCPServer server that sends a text message to a phone number via https://surgemsg.com/.
+
+To run this example, create a `.env` file with the following values:
+
+SURGE_API_KEY=...
+SURGE_ACCOUNT_ID=...
+SURGE_MY_PHONE_NUMBER=...
+SURGE_MY_FIRST_NAME=...
+SURGE_MY_LAST_NAME=...
+
+Visit https://surgemsg.com/ and click "Get Started" to obtain these values.
+"""
+
+from typing import Annotated
+
+import httpx2
+from pydantic import BeforeValidator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from mcp.server.mcpserver import MCPServer
+
+
+class SurgeSettings(BaseSettings):
+    model_config: SettingsConfigDict = SettingsConfigDict(env_prefix="SURGE_", env_file=".env")
+
+    api_key: str
+    account_id: str
+    my_phone_number: Annotated[str, BeforeValidator(lambda v: "+" + v if not v.startswith("+") else v)]
+    my_first_name: str
+    my_last_name: str
+
+
+# Create server
+mcp = MCPServer("Text me")
+surge_settings = SurgeSettings()  # type: ignore
+
+
+@mcp.tool(name="textme", description="Send a text message to me")
+def text_me(text_content: str) -> str:
+    """Send a text message to a phone number via https://surgemsg.com/"""
+    with httpx2.Client() as client:
+        response = client.post(
+            "https://api.surgemsg.com/messages",
+            headers={
+                "Authorization": f"Bearer {surge_settings.api_key}",
+                "Surge-Account": surge_settings.account_id,
+                "Content-Type": "application/json",
+            },
+            json={
+                "body": text_content,
+                "conversation": {
+                    "contact": {
+                        "first_name": surge_settings.my_first_name,
+                        "last_name": surge_settings.my_last_name,
+                        "phone_number": surge_settings.my_phone_number,
+                    }
+                },
+            },
+        )
+        response.raise_for_status()
+        return f"Message sent: {text_content}"
diff --git a/examples/servers/simple-auth/mcp_simple_auth/server.py b/examples/servers/simple-auth/mcp_simple_auth/server.py
index 89b0744329..0320871b12 100644
--- a/examples/servers/simple-auth/mcp_simple_auth/server.py
+++ b/examples/servers/simple-auth/mcp_simple_auth/server.py
@@ -12,7 +12,8 @@
 from typing import Any, Literal
 
 import click
-from pydantic import AnyHttpUrl, BaseModel
+from pydantic import AnyHttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from mcp.server.auth.settings import AuthSettings
 from mcp.server.mcpserver.server import MCPServer
@@ -22,9 +23,11 @@
 logger = logging.getLogger(__name__)
 
 
-class ResourceServerSettings(BaseModel):
+class ResourceServerSettings(BaseSettings):
     """Settings for the MCP Resource Server."""
 
+    model_config = SettingsConfigDict(env_prefix="MCP_RESOURCE_")
+
     # Server settings
     host: str = "localhost"
     port: int = 8001
diff --git a/examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py b/examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py
index 5d77ce24b9..48eb9a8414 100644
--- a/examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py
+++ b/examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py
@@ -12,7 +12,8 @@
 import time
 from typing import Any
 
-from pydantic import AnyHttpUrl, BaseModel
+from pydantic import AnyHttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
 from starlette.exceptions import HTTPException
 from starlette.requests import Request
 from starlette.responses import HTMLResponse, RedirectResponse, Response
@@ -28,9 +29,11 @@
 from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
 
 
-class SimpleAuthSettings(BaseModel):
+class SimpleAuthSettings(BaseSettings):
     """Simple OAuth settings for demo purposes."""
 
+    model_config = SettingsConfigDict(env_prefix="MCP_")
+
     # Demo user credentials
     demo_username: str = "demo_user"
     demo_password: str = "demo_password"
diff --git a/examples/servers/simple-auth/pyproject.toml b/examples/servers/simple-auth/pyproject.toml
index 89cc163c04..455db1e735 100644
--- a/examples/servers/simple-auth/pyproject.toml
+++ b/examples/servers/simple-auth/pyproject.toml
@@ -12,6 +12,7 @@ dependencies = [
     "httpx2>=2.5.0",
     "mcp",
     "pydantic>=2.0",
+    "pydantic-settings>=2.5.2",
     "sse-starlette>=1.6.1",
     "uvicorn>=0.23.1; sys_platform != 'emscripten'",
 ]
diff --git a/pyproject.toml b/pyproject.toml
index c0b1432ef7..5ce8812540 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -58,6 +58,9 @@ dev = [
     # We add mcp[cli] so `uv sync` considers the extras.
     "mcp[cli]",
     "mcp-example-stories",
+    # pydantic-settings is used only by examples (simple-auth, mcpserver/text_me);
+    # keep it reachable for pyright, which covers examples/servers.
+    "pydantic-settings>=2.5.2",
     "tomli>=2.0; python_version < '3.11'",
     "pyright>=1.1.400",
     "pytest>=8.4.0",
diff --git a/uv.lock b/uv.lock
index 39bb559859..b992b278aa 100644
--- a/uv.lock
+++ b/uv.lock
@@ -870,6 +870,7 @@ dev = [
     { name = "mcp-example-stories" },
     { name = "opentelemetry-sdk" },
     { name = "pillow" },
+    { name = "pydantic-settings" },
     { name = "pyright" },
     { name = "pytest" },
     { name = "pytest-examples" },
@@ -924,6 +925,7 @@ dev = [
     { name = "mcp-example-stories", editable = "examples" },
     { name = "opentelemetry-sdk", specifier = ">=1.39.1" },
     { name = "pillow", specifier = ">=12.0" },
+    { name = "pydantic-settings", specifier = ">=2.5.2" },
     { name = "pyright", specifier = ">=1.1.400" },
     { name = "pytest", specifier = ">=8.4.0" },
     { name = "pytest-examples", specifier = ">=0.0.14" },
@@ -1005,6 +1007,7 @@ dependencies = [
     { name = "httpx2" },
     { name = "mcp" },
     { name = "pydantic" },
+    { name = "pydantic-settings" },
     { name = "sse-starlette" },
     { name = "uvicorn", marker = "sys_platform != 'emscripten'" },
 ]
@@ -1023,6 +1026,7 @@ requires-dist = [
     { name = "httpx2", specifier = ">=2.5.0" },
     { name = "mcp" },
     { name = "pydantic", specifier = ">=2.0" },
+    { name = "pydantic-settings", specifier = ">=2.5.2" },
     { name = "sse-starlette", specifier = ">=1.6.1" },
     { name = "uvicorn", marker = "sys_platform != 'emscripten'", specifier = ">=0.23.1" },
 ]
@@ -1931,6 +1935,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/36/c7/cfc8e811f061c841d7990b0201912c3556bfeb99cdcb7ed24adc8d6f8704/pydantic_core-2.41.5-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:56121965f7a4dc965bff783d70b907ddf3d57f6eba29b6d2e5dabfaf07799c51", size = 2145302, upload-time = "2025-11-04T13:43:46.64Z" },
 ]
 
+[[package]]
+name = "pydantic-settings"
+version = "2.10.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+    { name = "python-dotenv" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/68/85/1ea668bbab3c50071ca613c6ab30047fb36ab0da1b92fa8f17bbc38fd36c/pydantic_settings-2.10.1.tar.gz", hash = "sha256:06f0062169818d0f5524420a360d632d5857b83cffd4d42fe29597807a1614ee", size = 172583, upload-time = "2025-06-24T13:26:46.841Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/58/f0/427018098906416f580e3cf1366d3b1abfb408a0652e9f31600c24a1903c/pydantic_settings-2.10.1-py3-none-any.whl", hash = "sha256:a60952460b99cf661dc25c29c0ef171721f98bfcb52ef8d9ea4c943d7c8cc796", size = 45235, upload-time = "2025-06-24T13:26:45.485Z" },
+]
+
 [[package]]
 name = "pygments"
 version = "2.20.0"