π The fast, Pythonic way to build MCP servers and clients.
Add `verify` parameter for SSL certificate configuration (#3487)
Jeremiah Lowin0b8479ad73fd
diff --git a/docs/clients/transports.mdx b/docs/clients/transports.mdxindex 7e3eb03db..efcda3366 100644--- a/docs/clients/transports.mdx+++ b/docs/clients/transports.mdx@@ -124,6 +124,38 @@ client = Client()```+### SSL Verification++By default, HTTPS connections verify the server's SSL certificate. You can customize this behavior with the `verify` parameter, which accepts the same values as [httpx](https://www.python-httpx.org/advanced/ssl/):++```python+from fastmcp import Client++# Disable SSL verification (e.g., for self-signed certs in development)+client = Client("https://dev-server.internal/mcp", verify=False)++# Use a custom CA bundle+client = Client("https://corp-server.internal/mcp", verify="/path/to/ca-bundle.pem")++# Use a custom SSL context for full control+import ssl+ctx = ssl.create_default_context()+ctx.load_verify_locations("/path/to/internal-ca.pem")+client = Client("https://corp-server.internal/mcp", verify=ctx)+```++The `verify` parameter is also available directly on `StreamableHttpTransport` and `SSETransport`:++```python+from fastmcp.client.transports import StreamableHttpTransport++transport = StreamableHttpTransport(+ url="https://dev-server.internal/mcp",+ verify=False,+)+client = Client(transport)+```+### SSE TransportServer-Sent Events transport is maintained for backward compatibility. Use Streamable HTTP for new deployments unless you have specific infrastructure requirements.diff --git a/src/fastmcp/client/client.py b/src/fastmcp/client/client.pyindex efacf671e..94cbbe169 100644--- a/src/fastmcp/client/client.py+++ b/src/fastmcp/client/client.py@@ -4,6 +4,7 @@ import asyncioimport copyimport datetimeimport secrets+import sslimport weakreffrom collections.abc import Coroutinefrom contextlib import AsyncExitStack, asynccontextmanager, suppress@@ -20,6 +21,7 @@ from mcp.types import GetTaskResult, TaskStatusNotificationfrom pydantic import AnyUrlimport fastmcp+from fastmcp.client.auth.oauth import OAuthfrom fastmcp.client.elicitation import ElicitationHandler, create_elicitation_callbackfrom fastmcp.client.logging import (LogHandler,@@ -258,10 +260,34 @@ class Client(init_timeout: datetime.timedelta | float | int | None = None,client_info: mcp.types.Implementation | None = None,auth: httpx.Auth | Literal["oauth"] | str | None = None,+ verify: ssl.SSLContext | bool | str | None = None,) -> None:self.name = name or self.generate_name()self.transport = cast(ClientTransportT, infer_transport(transport))++ if verify is not None:+ from fastmcp.client.transports.http import StreamableHttpTransport+ from fastmcp.client.transports.sse import SSETransport++ if isinstance(self.transport, StreamableHttpTransport | SSETransport):+ self.transport.verify = verify+ # Re-sync existing OAuth auth with the new verify setting,+ # but only if the transport doesn't have a custom factory+ # (which takes precedence and was already applied to OAuth).+ if (+ isinstance(self.transport.auth, OAuth)+ and auth is None+ and self.transport.httpx_client_factory is None+ ):+ verify_factory = self.transport._make_verify_factory()+ if verify_factory is not None:+ self.transport.auth.httpx_client_factory = verify_factory+ else:+ raise ValueError(+ "The 'verify' parameter is only supported for HTTP transports."+ )+if auth is not None:self.transport._set_auth(auth)diff --git a/src/fastmcp/client/transports/http.py b/src/fastmcp/client/transports/http.pyindex f7e74ca60..e4532c203 100644--- a/src/fastmcp/client/transports/http.py+++ b/src/fastmcp/client/transports/http.py@@ -4,8 +4,9 @@ from __future__ import annotationsimport contextlibimport datetime+import sslfrom collections.abc import AsyncIterator, Callable-from typing import Literal, cast+from typing import Any, Literal, castimport httpxfrom mcp import ClientSession@@ -32,6 +33,7 @@ class StreamableHttpTransport(ClientTransport):auth: httpx.Auth | Literal["oauth"] | str | None = None,sse_read_timeout: datetime.timedelta | float | int | None = None,httpx_client_factory: McpHttpClientFactory | None = None,+ verify: ssl.SSLContext | bool | str | None = None,):"""Initialize a Streamable HTTP transport.@@ -45,6 +47,10 @@ class StreamableHttpTransport(ClientTransport):If provided, must accept keyword arguments: headers, auth,follow_redirects, and optionally timeout. Using **kwargs isrecommended to ensure forward compatibility.+ verify: SSL certificate verification. Accepts False to disable+ verification, a path to a CA bundle, or an ssl.SSLContext+ for full control. None (default) uses httpx defaults (verification+ enabled). Ignored when httpx_client_factory is provided."""if isinstance(url, AnyUrl):url = str(url)@@ -57,6 +63,20 @@ class StreamableHttpTransport(ClientTransport):self.url: str = urlself.headers = headers or {}self.httpx_client_factory = httpx_client_factory+ self.verify: ssl.SSLContext | bool | str | None = verify++ if httpx_client_factory is not None and verify is not None:+ import warnings++ warnings.warn(+ "Both 'httpx_client_factory' and 'verify' were provided. "+ "The 'verify' parameter will be ignored because "+ "'httpx_client_factory' takes precedence. Configure SSL "+ "verification directly in your httpx_client_factory instead.",+ UserWarning,+ stacklevel=2,+ )+self._set_auth(auth)if sse_read_timeout is not None:@@ -78,9 +98,19 @@ class StreamableHttpTransport(ClientTransport):def _set_auth(self, auth: httpx.Auth | Literal["oauth"] | str | None):resolved: httpx.Auth | Noneif auth == "oauth":- resolved = OAuth(self.url, httpx_client_factory=self.httpx_client_factory)+ resolved = OAuth(+ self.url,+ httpx_client_factory=self.httpx_client_factory+ or self._make_verify_factory(),+ )elif isinstance(auth, OAuth):auth._bind(self.url)+ # Only inject the transport's factory into OAuth if OAuth still+ # has the bare default β preserve any factory the caller attached+ if auth.httpx_client_factory is httpx.AsyncClient:+ factory = self.httpx_client_factory or self._make_verify_factory()+ if factory is not None:+ auth.httpx_client_factory = factoryresolved = authelif isinstance(auth, str):resolved = BearerAuth(auth)@@ -88,6 +118,31 @@ class StreamableHttpTransport(ClientTransport):resolved = authself.auth: httpx.Auth | None = resolved+ def _make_verify_factory(self) -> McpHttpClientFactory | None:+ if self.verify is None:+ return None+ verify = self.verify++ def factory(+ headers: dict[str, str] | None = None,+ timeout: httpx.Timeout | None = None,+ auth: httpx.Auth | None = None,+ ) -> httpx.AsyncClient:+ if timeout is None:+ timeout = httpx.Timeout(30.0, read=300.0)+ kwargs: dict[str, Any] = {+ "follow_redirects": True,+ "timeout": timeout,+ "verify": verify,+ }+ if headers is not None:+ kwargs["headers"] = headers+ if auth is not None:+ kwargs["auth"] = auth+ return httpx.AsyncClient(**kwargs)++ return cast(McpHttpClientFactory, factory)+@contextlib.asynccontextmanagerasync def connect_session(self, **session_kwargs: Unpack[SessionKwargs]@@ -108,6 +163,7 @@ class StreamableHttpTransport(ClientTransport):# Create httpx client from factory or use default with MCP-appropriate timeouts# create_mcp_http_client uses 30s connect/5min read timeout by default,# and always enables follow_redirects+ verify_factory = self._make_verify_factory()if self.httpx_client_factory is not None:# Factory clients get the full kwargs for backwards compatibilityhttp_client = self.httpx_client_factory(@@ -116,6 +172,12 @@ class StreamableHttpTransport(ClientTransport):follow_redirects=True, # type: ignore[call-arg]**({"timeout": timeout} if timeout else {}),)+ elif verify_factory is not None:+ http_client = verify_factory(+ headers=headers,+ timeout=timeout,+ auth=self.auth,+ )else:http_client = create_mcp_http_client(headers=headers,diff --git a/src/fastmcp/client/transports/sse.py b/src/fastmcp/client/transports/sse.pyindex 36fa0ebc0..fa900eb7b 100644--- a/src/fastmcp/client/transports/sse.py+++ b/src/fastmcp/client/transports/sse.py@@ -4,6 +4,7 @@ from __future__ import annotationsimport contextlibimport datetime+import sslfrom collections.abc import AsyncIteratorfrom typing import Any, Literal, cast@@ -31,6 +32,7 @@ class SSETransport(ClientTransport):auth: httpx.Auth | Literal["oauth"] | str | None = None,sse_read_timeout: datetime.timedelta | float | int | None = None,httpx_client_factory: McpHttpClientFactory | None = None,+ verify: ssl.SSLContext | bool | str | None = None,):if isinstance(url, AnyUrl):url = str(url)@@ -43,6 +45,20 @@ class SSETransport(ClientTransport):self.url: str = urlself.headers = headers or {}self.httpx_client_factory = httpx_client_factory+ self.verify: ssl.SSLContext | bool | str | None = verify++ if httpx_client_factory is not None and verify is not None:+ import warnings++ warnings.warn(+ "Both 'httpx_client_factory' and 'verify' were provided. "+ "The 'verify' parameter will be ignored because "+ "'httpx_client_factory' takes precedence. Configure SSL "+ "verification directly in your httpx_client_factory instead.",+ UserWarning,+ stacklevel=2,+ )+self._set_auth(auth)self.sse_read_timeout = normalize_timeout_to_timedelta(sse_read_timeout)@@ -50,9 +66,19 @@ class SSETransport(ClientTransport):def _set_auth(self, auth: httpx.Auth | Literal["oauth"] | str | None):resolved: httpx.Auth | Noneif auth == "oauth":- resolved = OAuth(self.url, httpx_client_factory=self.httpx_client_factory)+ resolved = OAuth(+ self.url,+ httpx_client_factory=self.httpx_client_factory+ or self._make_verify_factory(),+ )elif isinstance(auth, OAuth):auth._bind(self.url)+ # Only inject the transport's factory into OAuth if OAuth still+ # has the bare default β preserve any factory the caller attached+ if auth.httpx_client_factory is httpx.AsyncClient:+ factory = self.httpx_client_factory or self._make_verify_factory()+ if factory is not None:+ auth.httpx_client_factory = factoryresolved = authelif isinstance(auth, str):resolved = BearerAuth(auth)@@ -60,6 +86,31 @@ class SSETransport(ClientTransport):resolved = authself.auth: httpx.Auth | None = resolved+ def _make_verify_factory(self) -> McpHttpClientFactory | None:+ if self.verify is None:+ return None+ verify = self.verify++ def factory(+ headers: dict[str, str] | None = None,+ timeout: httpx.Timeout | None = None,+ auth: httpx.Auth | None = None,+ ) -> httpx.AsyncClient:+ if timeout is None:+ timeout = httpx.Timeout(30.0, read=300.0)+ kwargs: dict[str, Any] = {+ "follow_redirects": True,+ "timeout": timeout,+ "verify": verify,+ }+ if headers is not None:+ kwargs["headers"] = headers+ if auth is not None:+ kwargs["auth"] = auth+ return httpx.AsyncClient(**kwargs)++ return cast(McpHttpClientFactory, factory)+@contextlib.asynccontextmanagerasync def connect_session(self, **session_kwargs: Unpack[SessionKwargs]@@ -85,6 +136,10 @@ class SSETransport(ClientTransport):if self.httpx_client_factory is not None:client_kwargs["httpx_client_factory"] = self.httpx_client_factory+ else:+ verify_factory = self._make_verify_factory()+ if verify_factory is not None:+ client_kwargs["httpx_client_factory"] = verify_factoryasync with sse_client(self.url, auth=self.auth, **client_kwargs) as transport:read_stream, write_stream = transportdiff --git a/tests/client/transports/test_transports.py b/tests/client/transports/test_transports.pyindex acf6001cb..1481aca25 100644--- a/tests/client/transports/test_transports.py+++ b/tests/client/transports/test_transports.py@@ -1,7 +1,12 @@+import sslfrom ssl import VerifyMode+from typing import castimport httpx+import pytest+from mcp.shared._httpx_utils import McpHttpClientFactory+from fastmcp import Clientfrom fastmcp.client.auth.oauth import OAuthfrom fastmcp.client.transports import SSETransport, StreamableHttpTransport@@ -40,3 +45,219 @@ async def test_oauth_uses_same_client_as_transport_sse():httpx_client._transport._pool._ssl_context.verify_mode # type: ignore[attr-defined]== VerifyMode.CERT_NONE)+++class TestSSLVerify:+ def test_streamable_http_transport_stores_verify_false(self):+ transport = StreamableHttpTransport(+ "https://example.com/mcp",+ verify=False,+ )+ assert transport.verify is False++ def test_streamable_http_transport_stores_verify_ssl_context(self):+ ctx = ssl.create_default_context()+ transport = StreamableHttpTransport(+ "https://example.com/mcp",+ verify=ctx,+ )+ assert transport.verify is ctx++ def test_streamable_http_transport_stores_verify_cert_path(self):+ transport = StreamableHttpTransport(+ "https://example.com/mcp",+ verify="/path/to/cert.pem",+ )+ assert transport.verify == "/path/to/cert.pem"++ def test_streamable_http_transport_verify_default_is_none(self):+ transport = StreamableHttpTransport("https://example.com/mcp")+ assert transport.verify is None++ def test_sse_transport_stores_verify_false(self):+ transport = SSETransport(+ "https://example.com/sse",+ verify=False,+ )+ assert transport.verify is False++ def test_sse_transport_stores_verify_ssl_context(self):+ ctx = ssl.create_default_context()+ transport = SSETransport(+ "https://example.com/sse",+ verify=ctx,+ )+ assert transport.verify is ctx++ def test_sse_transport_verify_default_is_none(self):+ transport = SSETransport("https://example.com/sse")+ assert transport.verify is None++ def test_client_passes_verify_to_streamable_http_transport(self):+ client = Client("https://example.com/mcp", verify=False)+ assert isinstance(client.transport, StreamableHttpTransport)+ assert client.transport.verify is False++ def test_client_passes_verify_ssl_context_to_transport(self):+ ctx = ssl.create_default_context()+ client = Client("https://example.com/mcp", verify=ctx)+ assert isinstance(client.transport, StreamableHttpTransport)+ assert client.transport.verify is ctx++ def test_client_passes_verify_cert_path_to_transport(self):+ client = Client(+ "https://example.com/mcp",+ verify="/path/to/cert.pem",+ )+ assert isinstance(client.transport, StreamableHttpTransport)+ assert client.transport.verify == "/path/to/cert.pem"++ def test_client_verify_none_leaves_transport_default(self):+ client = Client("https://example.com/mcp")+ assert isinstance(client.transport, StreamableHttpTransport)+ assert client.transport.verify is None++ def test_client_verify_raises_for_non_http_transport(self):+ from fastmcp import FastMCP++ server = FastMCP("test")+ with pytest.raises(+ ValueError,+ match="only supported for HTTP transports",+ ):+ Client(server, verify=False)++ def test_client_passes_verify_to_sse_transport(self):+ client = Client("https://example.com/sse", verify=False)+ assert isinstance(client.transport, SSETransport)+ assert client.transport.verify is False++ async def test_streamable_http_verify_propagates_to_oauth(self):+ transport = StreamableHttpTransport(+ "https://example.com/mcp",+ verify=False,+ auth="oauth",+ )+ assert isinstance(transport.auth, OAuth)+ async with transport.auth.httpx_client_factory() as httpx_client:+ assert (+ httpx_client._transport._pool._ssl_context.verify_mode # type: ignore[attr-defined]+ == VerifyMode.CERT_NONE+ )++ async def test_sse_verify_propagates_to_oauth(self):+ transport = SSETransport(+ "https://example.com/sse",+ verify=False,+ auth="oauth",+ )+ assert isinstance(transport.auth, OAuth)+ async with transport.auth.httpx_client_factory() as httpx_client:+ assert (+ httpx_client._transport._pool._ssl_context.verify_mode # type: ignore[attr-defined]+ == VerifyMode.CERT_NONE+ )++ async def test_client_verify_propagates_to_oauth(self):+ client = Client(+ "https://example.com/mcp",+ verify=False,+ auth="oauth",+ )+ assert isinstance(client.transport, StreamableHttpTransport)+ assert isinstance(client.transport.auth, OAuth)+ async with client.transport.auth.httpx_client_factory() as httpx_client:+ assert (+ httpx_client._transport._pool._ssl_context.verify_mode # type: ignore[attr-defined]+ == VerifyMode.CERT_NONE+ )++ async def test_verify_propagates_to_preconstructed_oauth_instance(self):+ transport = StreamableHttpTransport(+ "https://example.com/mcp",+ verify=False,+ auth=OAuth(),+ )+ assert isinstance(transport.auth, OAuth)+ async with transport.auth.httpx_client_factory() as httpx_client:+ assert (+ httpx_client._transport._pool._ssl_context.verify_mode # type: ignore[attr-defined]+ == VerifyMode.CERT_NONE+ )++ async def test_client_verify_resyncs_existing_oauth_on_transport(self):+ transport = StreamableHttpTransport(+ "https://example.com/mcp",+ auth="oauth",+ )+ assert isinstance(transport.auth, OAuth)+ # OAuth was created without verify β factory should be default+ async with transport.auth.httpx_client_factory() as httpx_client:+ assert (+ httpx_client._transport._pool._ssl_context.verify_mode # type: ignore[attr-defined]+ != VerifyMode.CERT_NONE+ )++ # Now wrap in Client with verify=False β should resync OAuth+ client = Client(transport, verify=False)+ assert isinstance(client.transport.auth, OAuth)+ async with client.transport.auth.httpx_client_factory() as httpx_client:+ assert (+ httpx_client._transport._pool._ssl_context.verify_mode+ == VerifyMode.CERT_NONE+ )++ async def test_client_verify_overrides_transport_verify_in_oauth(self):+ transport = StreamableHttpTransport(+ "https://example.com/mcp",+ verify=False,+ auth="oauth",+ )+ assert isinstance(transport.auth, OAuth)+ # OAuth should initially have verify=False+ async with transport.auth.httpx_client_factory() as httpx_client:+ assert (+ httpx_client._transport._pool._ssl_context.verify_mode # type: ignore[attr-defined]+ == VerifyMode.CERT_NONE+ )++ # Client overrides verify to True β OAuth should update+ client = Client(transport, verify=True)+ assert isinstance(client.transport.auth, OAuth)+ async with client.transport.auth.httpx_client_factory() as httpx_client:+ assert (+ httpx_client._transport._pool._ssl_context.verify_mode+ != VerifyMode.CERT_NONE+ )++ async def test_oauth_custom_factory_preserved_with_verify(self):+ custom_factory = cast(+ McpHttpClientFactory,+ lambda **kwargs: httpx.AsyncClient(verify=False, **kwargs),+ )+ auth = OAuth(httpx_client_factory=custom_factory)+ transport = StreamableHttpTransport(+ "https://example.com/mcp",+ verify=True,+ auth=auth,+ )+ assert isinstance(transport.auth, OAuth)+ assert transport.auth.httpx_client_factory is custom_factory++ def test_warns_when_both_factory_and_verify_provided_streamable(self):+ factory = cast(McpHttpClientFactory, httpx.AsyncClient)+ with pytest.warns(UserWarning, match="httpx_client_factory.*takes precedence"):+ StreamableHttpTransport(+ "https://example.com/mcp",+ httpx_client_factory=factory,+ verify=False,+ )++ def test_warns_when_both_factory_and_verify_provided_sse(self):+ factory = cast(McpHttpClientFactory, httpx.AsyncClient)+ with pytest.warns(UserWarning, match="httpx_client_factory.*takes precedence"):+ SSETransport(+ "https://example.com/sse",+ httpx_client_factory=factory,+ verify=False,+ )