Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(backend): speak MCP 2026-07-28 alongside legacy servers (#14302)

Krzysztof Czerwinskibe009da1c461
diff --git a/autogpt_platform/backend/backend/api/features/mcp/routes.py b/autogpt_platform/backend/backend/api/features/mcp/routes.py
index a13ebc0e33..07f1a599ad 100644
--- a/autogpt_platform/backend/backend/api/features/mcp/routes.py
+++ b/autogpt_platform/backend/backend/api/features/mcp/routes.py
@@ -7,6 +7,7 @@ frontend can list available tools on an MCP server before placing a block.
import logging
from typing import Annotated, Any
+from urllib.parse import urlparse
import fastapi
from autogpt_libs.auth import get_user_id
@@ -140,6 +141,9 @@ async def discover_tools(
status_code=502,
detail=f"Failed to connect to MCP server: {e}",
)
+ finally:
+ # Release any legacy session; a no-op on stateless servers.
+ await client.close()
return DiscoverToolsResponse(
tools=[
@@ -206,10 +210,14 @@ async def mcp_oauth_login(
protected_resource = await client.discover_auth()
metadata: dict[str, Any] | None = None
+ # The issuer the metadata document must declare, decided by which
+ # well-known URL answered; its ``issuer`` is only trusted when it matches
+ # (RFC 8414 §3.3).
+ expected_issuer = server_url
if protected_resource and protected_resource.get("authorization_servers"):
auth_server_url = protected_resource["authorization_servers"][0]
- resource_url = protected_resource.get("resource", server_url)
+ resource_url = _trusted_resource(protected_resource.get("resource"), server_url)
# Validate the auth server URL from metadata to prevent SSRF.
try:
@@ -221,14 +229,18 @@ async def mcp_oauth_login(
)
# Step 2a: Discover auth-server metadata (RFC 8414)
- metadata = await client.discover_auth_server_metadata(auth_server_url)
+ discovered = await client.discover_auth_server_metadata(auth_server_url)
+ if discovered:
+ metadata, expected_issuer = discovered
else:
# Fallback: Some MCP servers (e.g. Linear) are their own auth server
# and serve OAuth metadata directly without protected-resource metadata.
# Don't assume a resource_url — omitting it lets the auth server choose
# the correct audience for the token (RFC 8707 resource is optional).
resource_url = None
- metadata = await client.discover_auth_server_metadata(server_url)
+ discovered = await client.discover_auth_server_metadata(server_url)
+ if discovered:
+ metadata, expected_issuer = discovered
if (
not metadata
@@ -278,6 +290,14 @@ async def mcp_oauth_login(
scopes = (protected_resource or {}).get("scopes_supported") or metadata.get(
"scopes_supported", []
)
+ # RFC 8414 issuer identifier: validated against the ``iss``
+ # authorization-response parameter (RFC 9207) on callback, and recorded
+ # on the credential so it stays bound to the authorization server that
+ # issued it. Servers that advertise ``iss`` support must send it.
+ issuer = _validated_issuer(metadata, expected_issuer)
+ iss_required = bool(issuer) and (
+ metadata.get("authorization_response_iss_parameter_supported") is True
+ )
state_token, code_challenge = await creds_manager.store.store_state_token(
user_id,
ProviderName.MCP.value,
@@ -290,6 +310,8 @@ async def mcp_oauth_login(
"server_url": server_url,
"client_id": client_id,
"client_secret": client_secret,
+ "issuer": issuer,
+ "iss_required": iss_required,
},
)
@@ -314,6 +336,12 @@ class MCPOAuthCallbackRequest(BaseModel):
code: str = Field(description="Authorization code from OAuth callback")
state_token: str = Field(description="State token for CSRF verification")
+ iss: str | None = Field(
+ default=None,
+ description="Issuer identifier from the authorization response (RFC 9207). "
+ "Must match the authorization server discovered at login; required when "
+ "that server advertises `authorization_response_iss_parameter_supported`.",
+ )
class MCPOAuthCallbackResponse(BaseModel):
@@ -347,6 +375,24 @@ async def mcp_oauth_callback(
)
meta = valid_state.state_metadata
+ expected_issuer = meta.get("issuer") or ""
+ # RFC 9207 / MCP 2026-07-28: ``iss`` must match the issuer discovered at
+ # login, otherwise the code may come from a mix-up attack. A server that
+ # advertises ``iss`` support must send it; older servers may omit it.
+ if request.iss is None:
+ if meta.get("iss_required"):
+ raise fastapi.HTTPException(
+ status_code=400,
+ detail="Authorization response is missing the issuer identifier "
+ "the authorization server advertised it would send.",
+ )
+ elif expected_issuer and request.iss != expected_issuer:
+ raise fastapi.HTTPException(
+ status_code=400,
+ detail="Authorization response issuer does not match the "
+ "authorization server this login was started with.",
+ )
+
frontend_base_url = settings.config.frontend_base_url
if not frontend_base_url:
raise fastapi.HTTPException(
@@ -383,6 +429,7 @@ async def mcp_oauth_callback(
credentials.metadata["mcp_client_secret"] = meta.get("client_secret", "")
credentials.metadata["mcp_token_url"] = meta["token_url"]
credentials.metadata["mcp_resource_url"] = meta.get("resource_url", "")
+ credentials.metadata["mcp_issuer"] = expected_issuer
hostname = server_host(meta["server_url"])
credentials.title = f"MCP: {hostname}"
@@ -532,6 +579,89 @@ async def mcp_store_token(
# ======================== Helpers ======================== #
+_DEFAULT_PORTS = {"http": "80", "https": "443"}
+
+
+def _origin(url: str) -> tuple[str, str]:
+ parsed = urlparse(url)
+ scheme = parsed.scheme.lower()
+ host = parsed.netloc.lower()
+ # An explicit default port names the same origin as an absent one, so
+ # ``https://host:443`` must not read as a different server to ``https://host``.
+ default_port = _DEFAULT_PORTS.get(scheme)
+ if default_port and host.endswith(f":{default_port}"):
+ host = host[: -len(default_port) - 1]
+ return scheme, host
+
+
+def _trusted_resource(resource: Any, server_url: str) -> str:
+ """The protected-resource ``resource`` identifier, if it names *server_url*.
+
+ RFC 9728 §3.3 requires it to be the URL the metadata was fetched for. A
+ server naming another origin would have us request a token minted for a
+ different API and then send it to itself (a mix-up); in that case the
+ server URL is used as the resource indicator instead.
+ """
+ if not isinstance(resource, str) or not resource:
+ return server_url
+ if _origin(resource) != _origin(server_url):
+ logger.warning(
+ "Ignoring resource %r from %s: it names another origin",
+ resource,
+ server_host(server_url),
+ )
+ return server_url
+ return resource
+
+
+def _canonical_issuer(url: str) -> str:
+ """*url* with the scheme and host lowercased and a trailing slash dropped.
+
+ Scheme and host are case-insensitive (RFC 3986 §3.1, §3.2.2); the path is
+ not, so it is compared verbatim.
+ """
+ scheme, host = _origin(url)
+ return f"{scheme}://{host}{urlparse(url).path.rstrip('/')}"
+
+
+def _validated_issuer(metadata: dict[str, Any], expected_issuer: str) -> str:
+ """The metadata's ``issuer``, rejecting the document if it names another.
+
+ RFC 8414 §3.3 requires the issuer in the metadata document to be the URL
+ the document was fetched for. A document declaring someone else's issuer
+ is rejected outright rather than having just its issuer dropped: leaving
+ the issuer empty would set ``iss_required`` to ``False`` and turn the
+ callback's mismatch check into a no-op, so a hostile authorization server
+ could disable RFC 9207 mix-up protection by claiming, say,
+ ``https://accounts.google.com``. We either trust this document or we do
+ not; trusting its endpoints while discarding its issuer is the worst of
+ both.
+
+ A document that declares no issuer at all is a different case: it claims
+ nothing, so there is nothing to bind and nothing to disbelieve. Mix-up
+ protection is simply unavailable, which is how servers predating RFC 9207
+ behave.
+ """
+ issuer = metadata.get("issuer")
+ if not isinstance(issuer, str) or not issuer:
+ return ""
+ if _canonical_issuer(issuer) != _canonical_issuer(expected_issuer):
+ logger.warning(
+ "Rejecting metadata from %s: it declares issuer %r, which names "
+ "another server",
+ server_host(expected_issuer),
+ issuer,
+ )
+ raise fastapi.HTTPException(
+ status_code=400,
+ detail="This MCP server's authorization server metadata declares "
+ "an issuer that does not match where the metadata was published. "
+ "Sign-in was stopped because the server's identity cannot be "
+ "verified.",
+ )
+ return issuer
+
+
async def _register_mcp_client(
registration_endpoint: str,
redirect_uri: str,
@@ -547,6 +677,9 @@ async def _register_mcp_client(
"grant_types": ["authorization_code"],
"response_types": ["code"],
"token_endpoint_auth_method": "client_secret_post",
+ # Required by MCP 2026-07-28 so OIDC-backed authorization
+ # servers apply web-app redirect URI rules.
+ "application_type": "web",
},
)
data = response.json()
diff --git a/autogpt_platform/backend/backend/api/features/mcp/test_routes.py b/autogpt_platform/backend/backend/api/features/mcp/test_routes.py
index 77d9dc4c3e..63deda6f8c 100644
--- a/autogpt_platform/backend/backend/api/features/mcp/test_routes.py
+++ b/autogpt_platform/backend/backend/api/features/mcp/test_routes.py
@@ -4,7 +4,7 @@ Uses httpx.AsyncClient with ASGITransport instead of fastapi.testclient.TestClie
to avoid creating blocking portals that can corrupt pytest-asyncio's session event loop.
"""
-from unittest.mock import AsyncMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
import fastapi
import httpx
@@ -75,6 +75,7 @@ class TestDiscoverTools:
),
):
instance = MockClient.return_value
+ instance.close = AsyncMock()
instance.initialize = AsyncMock(
return_value={
"protocolVersion": "2025-03-26",
@@ -95,11 +96,13 @@ class TestDiscoverTools:
assert data["tools"][1]["name"] == "add_numbers"
assert data["server_name"] == "test-server"
assert data["protocol_version"] == "2025-03-26"
+ instance.close.assert_awaited_once()
@pytest.mark.asyncio(loop_scope="session")
async def test_discover_tools_with_auth_token(self, client):
with patch("backend.api.features.mcp.routes.MCPClient") as MockClient:
instance = MockClient.return_value
+ instance.close = AsyncMock()
instance.initialize = AsyncMock(
return_value={"serverInfo": {}, "protocolVersion": "2025-03-26"}
)
@@ -142,6 +145,7 @@ class TestDiscoverTools:
),
):
instance = MockClient.return_value
+ instance.close = AsyncMock()
instance.initialize = AsyncMock(
return_value={"serverInfo": {}, "protocolVersion": "2025-03-26"}
)
@@ -169,6 +173,7 @@ class TestDiscoverTools:
),
):
instance = MockClient.return_value
+ instance.close = AsyncMock()
instance.initialize = AsyncMock(
side_effect=MCPClientError("Connection refused")
)
@@ -180,6 +185,8 @@ class TestDiscoverTools:
assert response.status_code == 502
assert "Connection refused" in response.json()["detail"]
+ # The session is released on the error path too, not just on success.
+ instance.close.assert_awaited_once()
@pytest.mark.asyncio(loop_scope="session")
async def test_discover_tools_generic_error(self, client):
@@ -192,6 +199,7 @@ class TestDiscoverTools:
),
):
instance = MockClient.return_value
+ instance.close = AsyncMock()
instance.initialize = AsyncMock(side_effect=Exception("Network timeout"))
response = await client.post(
@@ -213,6 +221,7 @@ class TestDiscoverTools:
),
):
instance = MockClient.return_value
+ instance.close = AsyncMock()
instance.initialize = AsyncMock(
side_effect=HTTPClientError("HTTP 401 Error: Unauthorized", 401)
)
@@ -236,6 +245,7 @@ class TestDiscoverTools:
),
):
instance = MockClient.return_value
+ instance.close = AsyncMock()
instance.initialize = AsyncMock(
side_effect=HTTPClientError("HTTP 403 Error: Forbidden", 403)
)
@@ -274,11 +284,14 @@ class TestOAuthLogin:
}
)
instance.discover_auth_server_metadata = AsyncMock(
- return_value={
- "authorization_endpoint": "https://auth.sentry.io/authorize",
- "token_endpoint": "https://auth.sentry.io/token",
- "registration_endpoint": "https://auth.sentry.io/register",
- }
+ return_value=(
+ {
+ "authorization_endpoint": "https://auth.sentry.io/authorize",
+ "token_endpoint": "https://auth.sentry.io/token",
+ "registration_endpoint": "https://auth.sentry.io/register",
+ },
+ "https://auth.sentry.io",
+ )
)
mock_register.return_value = {
"client_id": "registered-client-id",
@@ -332,11 +345,14 @@ class TestOAuthLogin:
}
)
instance.discover_auth_server_metadata = AsyncMock(
- return_value={
- "authorization_endpoint": "https://auth.example.com/authorize",
- "token_endpoint": "https://auth.example.com/token",
- # No registration_endpoint
- }
+ return_value=(
+ {
+ "authorization_endpoint": "https://auth.example.com/authorize",
+ "token_endpoint": "https://auth.example.com/token",
+ # No registration_endpoint
+ },
+ "https://auth.example.com",
+ )
)
mock_cm.store.store_state_token = AsyncMock(
return_value=("state-abc", "challenge-xyz")
@@ -352,6 +368,417 @@ class TestOAuthLogin:
data = response.json()
assert "autogpt-platform" in data["login_url"]
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_oauth_login_binds_issuer_and_iss_requirement(self, client):
+ with (
+ patch("backend.api.features.mcp.routes.MCPClient") as MockClient,
+ patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+ patch("backend.api.features.mcp.routes.settings") as mock_settings,
+ ):
+ instance = MockClient.return_value
+ instance.discover_auth = AsyncMock(
+ return_value={
+ "authorization_servers": ["https://auth.example.com/"],
+ "resource": "https://mcp.example.com/mcp",
+ }
+ )
+ instance.discover_auth_server_metadata = AsyncMock(
+ return_value=(
+ {
+ "issuer": "https://auth.example.com",
+ "authorization_endpoint": "https://auth.example.com/authorize",
+ "token_endpoint": "https://auth.example.com/token",
+ "authorization_response_iss_parameter_supported": True,
+ },
+ "https://auth.example.com",
+ )
+ )
+ mock_cm.store.store_state_token = AsyncMock(
+ return_value=("state-abc", "challenge-xyz")
+ )
+ mock_settings.config.frontend_base_url = "http://localhost:3000"
+
+ response = await client.post(
+ "/oauth/login",
+ json={"server_url": "https://mcp.example.com/mcp"},
+ )
+
+ assert response.status_code == 200
+ state_metadata = mock_cm.store.store_state_token.call_args.kwargs[
+ "state_metadata"
+ ]
+ assert state_metadata["issuer"] == "https://auth.example.com"
+ assert state_metadata["iss_required"] is True
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_oauth_login_rejects_issuer_naming_another_server(self, client):
+ """RFC 8414 §3.3: a document naming another issuer is refused outright.
+
+ Dropping just the issuer would leave ``iss_required`` false and make
+ the callback's mismatch check a no-op, so a hostile authorization
+ server could switch off RFC 9207 mix-up protection by claiming a
+ well-known issuer.
+ """
+ with (
+ patch("backend.api.features.mcp.routes.MCPClient") as MockClient,
+ patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+ patch("backend.api.features.mcp.routes.settings") as mock_settings,
+ ):
+ instance = MockClient.return_value
+ instance.discover_auth = AsyncMock(
+ return_value={
+ "authorization_servers": ["https://auth.example.com"],
+ "resource": "https://mcp.example.com/mcp",
+ }
+ )
+ instance.discover_auth_server_metadata = AsyncMock(
+ return_value=(
+ {
+ "issuer": "https://evil.example.net",
+ "authorization_endpoint": "https://auth.example.com/authorize",
+ "token_endpoint": "https://auth.example.com/token",
+ "authorization_response_iss_parameter_supported": True,
+ },
+ "https://auth.example.com",
+ )
+ )
+ mock_cm.store.store_state_token = AsyncMock(
+ return_value=("state-abc", "challenge-xyz")
+ )
+ mock_settings.config.frontend_base_url = "http://localhost:3000"
+
+ response = await client.post(
+ "/oauth/login",
+ json={"server_url": "https://mcp.example.com/mcp"},
+ )
+
+ assert response.status_code == 400
+ assert "does not match where the metadata was published" in (
+ response.json()["detail"]
+ )
+ mock_cm.store.store_state_token.assert_not_awaited()
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_oauth_login_accepts_issuer_differing_only_in_case(self, client):
+ """Scheme and host are case-insensitive (RFC 3986), so this is a match."""
+ with (
+ patch("backend.api.features.mcp.routes.MCPClient") as MockClient,
+ patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+ patch("backend.api.features.mcp.routes.settings") as mock_settings,
+ ):
+ instance = MockClient.return_value
+ instance.discover_auth = AsyncMock(
+ return_value={
+ "authorization_servers": ["https://auth.example.com"],
+ "resource": "https://mcp.example.com/mcp",
+ }
+ )
+ instance.discover_auth_server_metadata = AsyncMock(
+ return_value=(
+ {
+ "issuer": "https://AUTH.Example.COM",
+ "authorization_endpoint": "https://auth.example.com/authorize",
+ "token_endpoint": "https://auth.example.com/token",
+ },
+ "https://auth.example.com",
+ )
+ )
+ mock_cm.store.store_state_token = AsyncMock(
+ return_value=("state-abc", "challenge-xyz")
+ )
+ mock_settings.config.frontend_base_url = "http://localhost:3000"
+
+ response = await client.post(
+ "/oauth/login",
+ json={"server_url": "https://mcp.example.com/mcp"},
+ )
+
+ assert response.status_code == 200
+ state_metadata = mock_cm.store.store_state_token.call_args.kwargs[
+ "state_metadata"
+ ]
+ assert state_metadata["issuer"] == "https://AUTH.Example.COM"
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_oauth_login_rejects_tenant_issuer_naming_bare_origin(self, client):
+ """A tenant's document may not claim the whole origin as its issuer.
+
+ The expected issuer comes from whichever well-known URL answered, so a
+ document fetched for ``/tenantA`` cannot pass by naming the origin
+ that ``/tenantB`` also lives under.
+ """
+ with (
+ patch("backend.api.features.mcp.routes.MCPClient") as MockClient,
+ patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+ patch("backend.api.features.mcp.routes.settings") as mock_settings,
+ ):
+ instance = MockClient.return_value
+ instance.discover_auth = AsyncMock(
+ return_value={
+ "authorization_servers": ["https://auth.example.com/tenantA"],
+ "resource": "https://mcp.example.com/mcp",
+ }
+ )
+ instance.discover_auth_server_metadata = AsyncMock(
+ return_value=(
+ {
+ "issuer": "https://auth.example.com",
+ "authorization_endpoint": "https://auth.example.com/authorize",
+ "token_endpoint": "https://auth.example.com/token",
+ },
+ "https://auth.example.com/tenantA",
+ )
+ )
+ mock_cm.store.store_state_token = AsyncMock(
+ return_value=("state-abc", "challenge-xyz")
+ )
+ mock_settings.config.frontend_base_url = "http://localhost:3000"
+
+ response = await client.post(
+ "/oauth/login",
+ json={"server_url": "https://mcp.example.com/mcp"},
+ )
+
+ assert response.status_code == 400
+ mock_cm.store.store_state_token.assert_not_awaited()
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_oauth_login_allows_metadata_without_an_issuer(self, client):
+ """No issuer claimed means no mix-up protection, not a hostile server."""
+ with (
+ patch("backend.api.features.mcp.routes.MCPClient") as MockClient,
+ patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+ patch("backend.api.features.mcp.routes.settings") as mock_settings,
+ ):
+ instance = MockClient.return_value
+ instance.discover_auth = AsyncMock(
+ return_value={
+ "authorization_servers": ["https://auth.example.com"],
+ "resource": "https://mcp.example.com/mcp",
+ }
+ )
+ instance.discover_auth_server_metadata = AsyncMock(
+ return_value=(
+ {
+ "authorization_endpoint": "https://auth.example.com/authorize",
+ "token_endpoint": "https://auth.example.com/token",
+ },
+ "https://auth.example.com",
+ )
+ )
+ mock_cm.store.store_state_token = AsyncMock(
+ return_value=("state-abc", "challenge-xyz")
+ )
+ mock_settings.config.frontend_base_url = "http://localhost:3000"
+
+ response = await client.post(
+ "/oauth/login",
+ json={"server_url": "https://mcp.example.com/mcp"},
+ )
+
+ assert response.status_code == 200
+ state_metadata = mock_cm.store.store_state_token.call_args.kwargs[
+ "state_metadata"
+ ]
+ assert state_metadata["issuer"] == ""
+ assert state_metadata["iss_required"] is False
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_oauth_login_ignores_resource_on_another_origin(self, client):
+ """RFC 9728 §3.3: a hostile server must not pick the token audience."""
+ with (
+ patch("backend.api.features.mcp.routes.MCPClient") as MockClient,
+ patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+ patch("backend.api.features.mcp.routes.settings") as mock_settings,
+ ):
+ instance = MockClient.return_value
+ instance.discover_auth = AsyncMock(
+ return_value={
+ "authorization_servers": ["https://as.legit.example"],
+ "resource": "https://api.legit.example/mcp",
+ }
+ )
+ instance.discover_auth_server_metadata = AsyncMock(
+ return_value=(
+ {
+ "authorization_endpoint": "https://as.legit.example/authorize",
+ "token_endpoint": "https://as.legit.example/token",
+ },
+ "https://as.legit.example",
+ )
+ )
+ mock_cm.store.store_state_token = AsyncMock(
+ return_value=("state-abc", "challenge-xyz")
+ )
+ mock_settings.config.frontend_base_url = "http://localhost:3000"
+
+ response = await client.post(
+ "/oauth/login",
+ json={"server_url": "https://evil.example/mcp"},
+ )
+
+ assert response.status_code == 200
+ state_metadata = mock_cm.store.store_state_token.call_args.kwargs[
+ "state_metadata"
+ ]
+ assert state_metadata["resource_url"] == "https://evil.example/mcp"
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_dynamic_client_registration_declares_web_application(self):
+ from backend.api.features.mcp.routes import _register_mcp_client
+
+ with patch("backend.api.features.mcp.routes.Requests") as MockRequests:
+ post = MockRequests.return_value.post = AsyncMock()
+ post.return_value = MagicMock()
+ post.return_value.json.return_value = {"client_id": "cid"}
+
+ result = await _register_mcp_client(
+ "https://auth.example.com/register",
+ "http://localhost:3000/auth/integrations/mcp_callback",
+ "https://mcp.example.com/mcp",
+ )
+
+ assert result == {"client_id": "cid"}
+ payload = post.call_args.kwargs["json"]
+ assert payload["application_type"] == "web"
+ assert payload["redirect_uris"] == [
+ "http://localhost:3000/auth/integrations/mcp_callback"
+ ]
+
+
+def _callback_mocks(mock_cm, mock_settings, MockHandler, state_metadata):
+ """Wire the mocks a successful ``/oauth/callback`` needs."""
+ mock_settings.config.frontend_base_url = "http://localhost:3000"
+ mock_state = AsyncMock()
+ mock_state.state_metadata = {
+ "authorize_url": "https://auth.example.com/authorize",
+ "token_url": "https://auth.example.com/token",
+ "client_id": "cid",
+ "server_url": "https://mcp.example.com/mcp",
+ **state_metadata,
+ }
+ mock_state.scopes = []
+ mock_state.code_verifier = "v"
+ mock_cm.store.verify_state_token = AsyncMock(return_value=mock_state)
+ mock_cm.store.get_creds_by_provider = AsyncMock(return_value=[])
+ mock_cm.create = AsyncMock()
+ creds = OAuth2Credentials(
+ provider="mcp",
+ title=None,
+ access_token=SecretStr("access-token"),
+ refresh_token=None,
+ access_token_expires_at=None,
+ refresh_token_expires_at=None,
+ scopes=[],
+ metadata={},
+ )
+ MockHandler.return_value.exchange_code_for_tokens = AsyncMock(return_value=creds)
+ return creds
+
+
+class TestOAuthCallbackIssuer:
+ """RFC 9207 ``iss`` handling on the callback."""
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_mismatched_iss_is_rejected(self, client):
+ with (
+ patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+ patch("backend.api.features.mcp.routes.settings") as mock_settings,
+ patch("backend.api.features.mcp.routes.MCPOAuthHandler") as MockHandler,
+ ):
+ _callback_mocks(
+ mock_cm,
+ mock_settings,
+ MockHandler,
+ {"issuer": "https://auth.example.com", "iss_required": True},
+ )
+ response = await client.post(
+ "/oauth/callback",
+ json={
+ "code": "code",
+ "state_token": "state",
+ "iss": "https://evil.example.net",
+ },
+ )
+
+ assert response.status_code == 400
+ assert "issuer does not match" in response.json()["detail"]
+ MockHandler.return_value.exchange_code_for_tokens.assert_not_called()
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_missing_iss_is_rejected_when_server_advertises_it(self, client):
+ with (
+ patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+ patch("backend.api.features.mcp.routes.settings") as mock_settings,
+ patch("backend.api.features.mcp.routes.MCPOAuthHandler") as MockHandler,
+ ):
+ _callback_mocks(
+ mock_cm,
+ mock_settings,
+ MockHandler,
+ {"issuer": "https://auth.example.com", "iss_required": True},
+ )
+ response = await client.post(
+ "/oauth/callback",
+ json={"code": "code", "state_token": "state"},
+ )
+
+ assert response.status_code == 400
+ assert "missing the issuer" in response.json()["detail"]
+ MockHandler.return_value.exchange_code_for_tokens.assert_not_called()
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_missing_iss_is_accepted_for_servers_that_do_not_send_it(
+ self, client
+ ):
+ with (
+ patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+ patch("backend.api.features.mcp.routes.settings") as mock_settings,
+ patch("backend.api.features.mcp.routes.MCPOAuthHandler") as MockHandler,
+ ):
+ creds = _callback_mocks(
+ mock_cm,
+ mock_settings,
+ MockHandler,
+ {"issuer": "https://auth.example.com", "iss_required": False},
+ )
+ response = await client.post(
+ "/oauth/callback",
+ json={"code": "code", "state_token": "state"},
+ )
+
+ assert response.status_code == 200
+ assert creds.metadata is not None
+ assert creds.metadata["mcp_issuer"] == "https://auth.example.com"
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_matching_iss_binds_issuer_to_credential(self, client):
+ with (
+ patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+ patch("backend.api.features.mcp.routes.settings") as mock_settings,
+ patch("backend.api.features.mcp.routes.MCPOAuthHandler") as MockHandler,
+ ):
+ creds = _callback_mocks(
+ mock_cm,
+ mock_settings,
+ MockHandler,
+ {"issuer": "https://auth.example.com", "iss_required": True},
+ )
+ response = await client.post(
+ "/oauth/callback",
+ json={
+ "code": "code",
+ "state_token": "state",
+ "iss": "https://auth.example.com",
+ },
+ )
+
+ assert response.status_code == 200
+ mock_cm.create.assert_awaited_once()
+ assert creds.metadata is not None
+ assert creds.metadata["mcp_issuer"] == "https://auth.example.com"
+ assert creds.metadata["mcp_server_url"] == "https://mcp.example.com/mcp"
+
class TestOAuthCallback:
@pytest.mark.asyncio(loop_scope="session")
@@ -526,6 +953,7 @@ class TestStoreToken:
}
)
mcp_client.list_tools = AsyncMock(return_value=[])
+ mcp_client.close = AsyncMock()
discover_response = await client.post(
"/discover-tools",
@@ -536,6 +964,7 @@ class TestStoreToken:
client_cls.assert_called_once_with(
"https://mcp.example.com/mcp", authorization="Basic encoded-value"
)
+ mcp_client.close.assert_awaited_once()
manager.refresh_if_needed.assert_not_awaited()
@pytest.mark.asyncio(loop_scope="session")
diff --git a/autogpt_platform/backend/backend/blocks/mcp/block.py b/autogpt_platform/backend/backend/blocks/mcp/block.py
index 8948f07b1a..f3d00e5413 100644
--- a/autogpt_platform/backend/backend/blocks/mcp/block.py
+++ b/autogpt_platform/backend/backend/blocks/mcp/block.py
@@ -174,11 +174,17 @@ class MCPToolBlock(Block):
tool_name: str,
arguments: dict[str, Any],
authorization: str | None = None,
+ input_schema: dict[str, Any] | None = None,
) -> Any:
"""Call a tool on the MCP server. Extracted for easy mocking in tests."""
client = MCPClient(server_url, authorization=authorization)
- await client.initialize()
- result = await client.call_tool(tool_name, arguments)
+ try:
+ await client.initialize()
+ result = await client.call_tool(
+ tool_name, arguments, input_schema=input_schema
+ )
+ finally:
+ await client.close()
if result.is_error:
error_text = ""
@@ -252,6 +258,7 @@ class MCPToolBlock(Block):
tool_name=input_data.selected_tool,
arguments=input_data.tool_arguments,
authorization=authorization,
+ input_schema=input_data.tool_input_schema or None,
)
yield "result", result
except MCPClientError as e:
diff --git a/autogpt_platform/backend/backend/blocks/mcp/client.py b/autogpt_platform/backend/backend/blocks/mcp/client.py
index aceb14b46d..57ec4903a7 100644
--- a/autogpt_platform/backend/backend/blocks/mcp/client.py
+++ b/autogpt_platform/backend/backend/blocks/mcp/client.py
@@ -6,18 +6,65 @@ on remote MCP servers. Uses JSON-RPC 2.0 over HTTP POST.
Handles both JSON and SSE (text/event-stream) response formats per the MCP spec.
-Reference: https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
+The client is *dual-era*: it speaks the stateless ``2026-07-28`` revision and
+falls back to the ``initialize``-handshake revisions (``2025-03-26``) for
+servers that have not upgraded. Era detection follows the spec's HTTP
+backward-compatibility rules and is cached per server URL so legacy servers do
+not pay for a failed modern probe on every connection.
+
+References:
+ https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http
+ https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning
+ https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
"""
import json
import logging
-from dataclasses import dataclass, field
-from typing import Any
-
-from backend.util.request import Requests
+from typing import Any, NoReturn
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from backend.blocks.mcp.protocol import (
+ CLIENT_INFO,
+ ERROR_HEADER_MISMATCH,
+ ERROR_METHOD_NOT_FOUND,
+ ERROR_MISSING_CLIENT_CAPABILITY,
+ ERROR_UNSUPPORTED_PROTOCOL_VERSION,
+ HEADER_METHOD,
+ HEADER_NAME,
+ HEADER_PROTOCOL_VERSION,
+ HEADER_SESSION_ID,
+ LEGACY_PROTOCOL_VERSION,
+ META_SERVER_INFO,
+ MODERN_PROTOCOL_VERSION,
+ RESULT_TYPE_COMPLETE,
+ RESULT_TYPE_INPUT_REQUIRED,
+ HeaderParam,
+ InvalidHeaderAnnotation,
+ MCPProtocolEra,
+ MCPServerProtocol,
+ build_request_meta,
+ collect_header_params,
+ era_cache,
+ extract_header_params,
+ is_modern_jsonrpc_error,
+ jsonrpc_error_code,
+ name_header_for,
+ negotiate_version,
+)
+from backend.util.request import HTTPClientError, Requests, Response
logger = logging.getLogger(__name__)
+# HTTP statuses on which we must *not* guess the server's era: they say
+# something about our credentials or rate, not about the protocol.
+_NO_FALLBACK_STATUSES = frozenset({401, 403, 407, 429})
+# Bound on ``input_required`` retries when the server only wants its
+# ``requestState`` echoed back (no interactive input requested).
+_MAX_INPUT_REQUIRED_RETRIES = 3
+# ``Requests`` retries throttled/5xx responses forever unless told otherwise.
+# MCP calls run inside graph executions and chat turns, so keep them bounded.
+_HTTP_RETRY_ATTEMPTS = 3
_SUPPORTED_AUTH_SCHEMES = {
"basic": "Basic",
"bearer": "Bearer",
@@ -79,8 +126,7 @@ def normalize_mcp_authorization(value: str) -> str:
return f"{scheme} {credential}"
-@dataclass
-class MCPTool:
+class MCPTool(BaseModel):
"""Represents an MCP tool discovered from a server."""
name: str
@@ -88,11 +134,10 @@ class MCPTool:
input_schema: dict[str, Any]
-@dataclass
-class MCPCallResult:
+class MCPCallResult(BaseModel):
"""Result from calling an MCP tool."""
- content: list[dict[str, Any]] = field(default_factory=list)
+ content: list[dict[str, Any]] = Field(default_factory=list)
is_error: bool = False
@@ -102,11 +147,33 @@ class MCPClientError(Exception):
pass
+class _Reply(BaseModel):
+ """A decoded HTTP reply: status, parsed JSON-RPC body (if any), headers."""
+
+ model_config = ConfigDict(arbitrary_types_allowed=True)
+
+ status: int
+ body: dict[str, Any] | None
+ response: Response
+
+ @property
+ def result(self) -> Any:
+ return self.body.get("result") if self.body else None
+
+ @property
+ def error_code(self) -> int | None:
+ return jsonrpc_error_code(self.body)
+
+
class MCPClient:
"""
Async HTTP client for the MCP Streamable HTTP transport.
Communicates with MCP servers using JSON-RPC 2.0 over HTTP POST.
+ Speaks both the stateless ``2026-07-28`` protocol and the legacy
+ ``initialize``-handshake protocol; the era is detected on first contact
+ (see :meth:`initialize`) and remembered per server URL.
+
``authorization`` is sent verbatim as the ``Authorization`` header; callers
pass an already-canonical value.
"""
@@ -122,6 +189,11 @@ class MCPClient:
self.authorization = authorization
self._request_id = 0
self._session_id: str | None = None
+ self.era: MCPProtocolEra | None = None
+ self.protocol_version: str | None = None
+ self.server_info: dict[str, Any] = {}
+ self.server_capabilities: dict[str, Any] = {}
+ self._header_params: dict[str, list[HeaderParam]] = {}
def _next_id(self) -> int:
self._request_id += 1
@@ -135,7 +207,7 @@ class MCPClient:
if self.authorization:
headers["Authorization"] = self.authorization
if self._session_id:
- headers["Mcp-Session-Id"] = self._session_id
+ headers[HEADER_SESSION_ID] = self._session_id
return headers
def _build_jsonrpc_request(
@@ -179,54 +251,88 @@ class MCPClient:
raise MCPClientError("No JSON-RPC response found in SSE stream")
return last_data
- async def _send_request(
- self, method: str, params: dict[str, Any] | None = None
- ) -> Any:
- """Send a JSON-RPC request to the MCP server and return the result.
+ # ───────────────────────── HTTP plumbing ─────────────────────────
- Handles both ``application/json`` and ``text/event-stream`` responses
- as required by the MCP Streamable HTTP transport specification.
- """
- payload = self._build_jsonrpc_request(method, params)
- headers = self._build_headers()
+ async def _post(self, payload: dict[str, Any], headers: dict[str, str]) -> Response:
+ """POST one JSON-RPC message and return the raw reply.
+
+ Status handling is done by the caller: modern era detection needs to
+ read the body of a ``400`` before deciding what it means.
+ ``tools/call`` is never retried: a tool may have applied its side
+ effect before the server answered with a retryable status, and the
+ spec gives no idempotency guarantee for re-sending it.
+ """
requests = Requests(
- raise_for_status=True,
+ raise_for_status=False,
+ retry_max_attempts=(
+ 1 if payload.get("method") == "tools/call" else _HTTP_RETRY_ATTEMPTS
+ ),
extra_headers=headers,
)
- response = await requests.post(self.server_url, json=payload)
+ return await requests.post(self.server_url, json=payload)
- # Capture session ID from response (MCP Streamable HTTP transport)
- session_id = response.headers.get("Mcp-Session-Id")
- if session_id:
- self._session_id = session_id
+ def _decode_reply(self, response: Response, *, strict: bool) -> _Reply:
+ """Decode a reply body as JSON or SSE.
+ With ``strict`` a body that isn't a JSON object raises; otherwise it
+ yields ``body=None`` so era detection can treat it as "not a modern
+ JSON-RPC error".
+ """
content_type = response.headers.get("content-type", "")
- if "text/event-stream" in content_type:
- body = self._parse_sse_response(response.text())
- else:
- try:
+ body: Any = None
+ try:
+ if "text/event-stream" in content_type:
+ body = self._parse_sse_response(response.text())
+ elif response.content.strip():
body = response.json()
- except Exception as e:
+ except MCPClientError:
+ if strict:
+ raise
+ except Exception as e:
+ if strict:
raise MCPClientError(
f"MCP server returned non-JSON response: {e}"
) from e
-
- if not isinstance(body, dict):
+ if strict and not isinstance(body, dict):
raise MCPClientError(
f"MCP server returned unexpected JSON type: {type(body).__name__}"
)
+ return _Reply(
+ status=response.status,
+ body=body if isinstance(body, dict) else None,
+ response=response,
+ )
- # Handle JSON-RPC error
- if "error" in body:
- error = body["error"]
- if isinstance(error, dict):
- raise MCPClientError(
- f"MCP server error [{error.get('code', '?')}]: "
- f"{error.get('message', 'Unknown error')}"
- )
- raise MCPClientError(f"MCP server error: {error}")
+ @staticmethod
+ def _raise_jsonrpc_error(body: dict[str, Any]) -> NoReturn:
+ error = body["error"]
+ if isinstance(error, dict):
+ raise MCPClientError(
+ f"MCP server error [{error.get('code', '?')}]: "
+ f"{error.get('message', 'Unknown error')}"
+ )
+ raise MCPClientError(f"MCP server error: {error}")
+
+ # ───────────────────────── legacy era ─────────────────────────
+
+ async def _send_legacy(
+ self, method: str, params: dict[str, Any] | None = None
+ ) -> Any:
+ """Legacy request: session header in, ``Mcp-Session-Id`` captured out."""
+ payload = self._build_jsonrpc_request(method, params)
+ response = await self._post(payload, self._build_headers())
+ response.raise_for_status()
+ session_id = response.headers.get(HEADER_SESSION_ID)
+ if session_id:
+ self._session_id = session_id
+
+ body = self._decode_reply(response, strict=True).body
+ if body is None:
+ raise MCPClientError("MCP server returned an empty response")
+ if "error" in body:
+ self._raise_jsonrpc_error(body)
return body.get("result")
async def _send_notification(self, method: str) -> None:
@@ -235,10 +341,338 @@ class MCPClient:
notification = {"jsonrpc": "2.0", "method": method}
requests = Requests(
raise_for_status=False,
+ retry_max_attempts=_HTTP_RETRY_ATTEMPTS,
extra_headers=headers,
)
await requests.post(self.server_url, json=notification)
+ async def _legacy_initialize(self) -> dict[str, Any]:
+ result = await self._send_legacy(
+ "initialize",
+ {
+ "protocolVersion": LEGACY_PROTOCOL_VERSION,
+ "capabilities": {},
+ "clientInfo": dict(CLIENT_INFO),
+ },
+ )
+ # Send initialized notification (no response expected)
+ await self._send_notification("notifications/initialized")
+ result = result or {}
+ self.protocol_version = result.get("protocolVersion") or LEGACY_PROTOCOL_VERSION
+ self.server_info = result.get("serverInfo") or {}
+ self.server_capabilities = result.get("capabilities") or {}
+ return result
+
+ # ───────────────────────── modern era ─────────────────────────
+
+ @staticmethod
+ def _server_info_from(result: Any) -> dict[str, Any] | None:
+ """``io.modelcontextprotocol/serverInfo`` from a modern result's ``_meta``."""
+ if not isinstance(result, dict):
+ return None
+ server_info = (result.get("_meta") or {}).get(META_SERVER_INFO)
+ return server_info if isinstance(server_info, dict) else None
+
+ def _modern_headers(
+ self, method: str, params: dict[str, Any] | None, protocol_version: str
+ ) -> dict[str, str]:
+ headers = self._build_headers()
+ headers.pop(HEADER_SESSION_ID, None)
+ headers[HEADER_PROTOCOL_VERSION] = protocol_version
+ headers[HEADER_METHOD] = method
+ name = name_header_for(method, params)
+ if name is not None:
+ headers[HEADER_NAME] = name
+ if method == "tools/call" and params:
+ header_params = self._header_params.get(str(params.get("name")))
+ if header_params:
+ headers.update(
+ extract_header_params(header_params, params.get("arguments"))
+ )
+ return headers
+
+ async def _post_modern(
+ self, method: str, params: dict[str, Any] | None, protocol_version: str
+ ) -> _Reply:
+ body_params = dict(params or {})
+ body_params["_meta"] = build_request_meta(protocol_version)
+ payload = self._build_jsonrpc_request(method, body_params)
+ headers = self._modern_headers(method, params, protocol_version)
+ response = await self._post(payload, headers)
+ return self._decode_reply(response, strict=False)
+
+ def _adopt_negotiated_version(self, reply: _Reply) -> str:
+ """Handle ``UnsupportedProtocolVersionError``: pick a shared version."""
+ error = (reply.body or {}).get("error") or {}
+ data = error.get("data") if isinstance(error, dict) else None
+ supported = data.get("supported") if isinstance(data, dict) else None
+ version = negotiate_version(supported)
+ if version is None:
+ raise MCPClientError(
+ "MCP server does not support any protocol version this client "
+ f"speaks (server offers: {supported or 'unknown'})"
+ )
+ self.protocol_version = version
+ return version
+
+ async def _send_modern(
+ self,
+ method: str,
+ params: dict[str, Any] | None = None,
+ *,
+ _retried_version: bool = False,
+ _retried_headers: bool = False,
+ ) -> Any:
+ version = self.protocol_version or MODERN_PROTOCOL_VERSION
+ reply = await self._post_modern(method, params, version)
+
+ if reply.status in _NO_FALLBACK_STATUSES or reply.status >= 500:
+ # Credential, rate-limit and server errors keep their HTTP meaning
+ # even when they carry a JSON-RPC envelope, so the auth flows in
+ # the routes and the copilot tool see the same exceptions as on
+ # the legacy path.
+ reply.response.raise_for_status()
+
+ code = reply.error_code
+ if code == ERROR_UNSUPPORTED_PROTOCOL_VERSION and not _retried_version:
+ self._adopt_negotiated_version(reply)
+ self._remember_era()
+ return await self._send_modern(
+ method,
+ params,
+ _retried_version=True,
+ _retried_headers=_retried_headers,
+ )
+
+ if (
+ code == ERROR_HEADER_MISMATCH
+ and method == "tools/call"
+ and params
+ and not _retried_headers
+ ):
+ # The server's tool definition may have gained ``x-mcp-header``
+ # annotations since we last listed tools: refresh and retry once.
+ await self._refresh_header_params()
+ return await self._send_modern(
+ method,
+ params,
+ _retried_version=_retried_version,
+ _retried_headers=True,
+ )
+
+ if code == ERROR_MISSING_CLIENT_CAPABILITY:
+ raise MCPClientError(
+ f"MCP server requires client capabilities this client does not "
+ f"provide for {method}: "
+ f"{(reply.body or {}).get('error', {}).get('data')}"
+ )
+
+ if reply.status == 404 and code == ERROR_METHOD_NOT_FOUND:
+ raise MCPClientError(f"MCP server does not support {method}")
+
+ if not reply.response.ok:
+ if reply.body and "error" in reply.body:
+ self._raise_jsonrpc_error(reply.body)
+ reply.response.raise_for_status()
+
+ if reply.body is None:
+ # 2xx without a usable JSON-RPC body: surface the same errors the
+ # strict decoder would have raised.
+ self._decode_reply(reply.response, strict=True)
+ raise MCPClientError("MCP server returned an empty response")
+
+ if "error" in reply.body:
+ self._raise_jsonrpc_error(reply.body)
+
+ result = reply.body.get("result")
+ result_type = result.get("resultType") if isinstance(result, dict) else None
+ if result_type not in (None, RESULT_TYPE_COMPLETE, RESULT_TYPE_INPUT_REQUIRED):
+ raise MCPClientError(
+ f"MCP server returned unrecognized resultType {result_type!r}"
+ )
+ server_info = self._server_info_from(result)
+ if server_info is not None:
+ self.server_info = server_info
+ return result
+
+ async def _refresh_header_params(self) -> None:
+ try:
+ await self.list_tools()
+ except Exception:
+ logger.debug("Could not refresh MCP tool schemas", exc_info=True)
+
+ @staticmethod
+ def _discover_result_to_init(
+ result: dict[str, Any], version: str
+ ) -> dict[str, Any]:
+ """Shape a ``server/discover`` result like an ``initialize`` result.
+
+ Callers written against the legacy handshake read ``protocolVersion``
+ and ``serverInfo`` from what :meth:`initialize` returns.
+ """
+ init = dict(result)
+ init["protocolVersion"] = version
+ init.setdefault("capabilities", {})
+ init["serverInfo"] = MCPClient._server_info_from(result) or {}
+ return init
+
+ # ───────────────────────── era detection ─────────────────────────
+
+ def _remember_era(self) -> None:
+ if self.era is not None and self.protocol_version:
+ era_cache.set(
+ self.server_url,
+ MCPServerProtocol(era=self.era, protocol_version=self.protocol_version),
+ )
+
+ def _forget_era(self) -> None:
+ """Drop a cached era assumption that just failed, before re-probing."""
+ era_cache.forget(self.server_url)
+ self.era = None
+ self.protocol_version = None
+ self._session_id = None
+
+ @staticmethod
+ def _is_credential_or_rate_error(error: Exception) -> bool:
+ return (
+ isinstance(error, HTTPClientError)
+ and error.status_code in _NO_FALLBACK_STATUSES
+ )
+
+ @classmethod
+ def _is_discover_result(cls, result: Any) -> bool:
+ """Does a ``server/discover`` reply look like a ``DiscoverResult``?
+
+ The spec requires ``supportedVersions``; be as lenient as
+ :meth:`_send_modern` is about ``resultType`` and accept any other
+ member of the result too. A legacy server never answers this method
+ with a result, only with ``-32601``.
+ """
+ if not isinstance(result, dict):
+ return False
+ members = ("supportedVersions", "capabilities", "resultType", "instructions")
+ return any(key in result for key in members) or (
+ cls._server_info_from(result) is not None
+ )
+
+ async def _probe_modern(self) -> dict[str, Any] | None:
+ """Send ``server/discover`` and classify the server's era.
+
+ Returns the discover result when the server is modern, ``None`` when
+ it is legacy. Raises for auth/rate/5xx statuses because those say
+ nothing about the era and callers already handle them.
+ """
+ version = MODERN_PROTOCOL_VERSION
+ reply = await self._post_modern("server/discover", None, version)
+
+ if reply.error_code == ERROR_UNSUPPORTED_PROTOCOL_VERSION:
+ version = self._adopt_negotiated_version(reply)
+ reply = await self._post_modern("server/discover", None, version)
+ if reply.error_code == ERROR_UNSUPPORTED_PROTOCOL_VERSION:
+ raise MCPClientError(
+ "MCP server rejected the protocol version it advertised"
+ )
+
+ if reply.status in _NO_FALLBACK_STATUSES or reply.status >= 500:
+ reply.response.raise_for_status()
+
+ if reply.response.ok:
+ result = reply.result
+ if self._is_discover_result(result):
+ self.protocol_version = version
+ return result
+ if is_modern_jsonrpc_error(reply.body):
+ self._raise_jsonrpc_error(reply.body or {})
+ # A legacy server answering an unknown method with a JSON-RPC
+ # error (``-32601``) or something else entirely.
+ return None
+
+ # 4xx: modern servers use 400 for header/version/capability errors and
+ # 404 + -32601 for unknown methods. server/discover is mandatory on
+ # modern servers, so a -32601 means legacy.
+ if is_modern_jsonrpc_error(reply.body):
+ self._raise_jsonrpc_error(reply.body or {})
+ return None
+
+ async def initialize(self) -> dict[str, Any]:
+ """
+ Establish contact with the server using whichever protocol era it speaks.
+
+ Modern servers (``2026-07-28``) are stateless: this sends
+ ``server/discover`` and records the negotiated version. Legacy servers
+ get the ``initialize`` / ``notifications/initialized`` handshake.
+
+ Returns an ``initialize``-shaped dict (``protocolVersion``,
+ ``serverInfo``, ``capabilities``) in both cases.
+ """
+ if self.era is None:
+ cached = era_cache.get(self.server_url)
+ if cached is not None:
+ self.era = cached.era
+ self.protocol_version = cached.protocol_version
+
+ if self.era is None:
+ result = await self._probe_modern()
+ if result is not None:
+ self.era = MCPProtocolEra.MODERN
+ self._remember_era()
+ return self._finish_modern_init(result)
+ self.era = MCPProtocolEra.LEGACY
+ self.protocol_version = None
+ result = await self._legacy_initialize()
+ self._remember_era()
+ return result
+
+ # A cached era is an assumption. If the matching handshake is rejected
+ # for a protocol-shaped reason (the server rolled back or upgraded),
+ # drop it and probe once from scratch. Credential and rate-limit
+ # errors say nothing about the era and propagate unchanged.
+ if self.era is MCPProtocolEra.MODERN:
+ try:
+ result = await self._send_modern("server/discover")
+ except (MCPClientError, HTTPClientError) as e:
+ if self._is_credential_or_rate_error(e):
+ raise
+ self._forget_era()
+ return await self.initialize()
+ return self._finish_modern_init(result if isinstance(result, dict) else {})
+
+ try:
+ result = await self._legacy_initialize()
+ except (MCPClientError, HTTPClientError) as e:
+ if self._is_credential_or_rate_error(e):
+ raise
+ self._forget_era()
+ return await self.initialize()
+ self._remember_era()
+ return result
+
+ def _finish_modern_init(self, result: dict[str, Any]) -> dict[str, Any]:
+ version = self.protocol_version or MODERN_PROTOCOL_VERSION
+ self.protocol_version = version
+ self.server_capabilities = result.get("capabilities") or {}
+ server_info = self._server_info_from(result)
+ if server_info is not None:
+ self.server_info = server_info
+ return self._discover_result_to_init(result, version)
+
+ # ───────────────────────── public API ─────────────────────────
+
+ async def _send_request(
+ self, method: str, params: dict[str, Any] | None = None
+ ) -> Any:
+ """Send a JSON-RPC request to the MCP server and return the result.
+
+ Handles both ``application/json`` and ``text/event-stream`` responses
+ as required by the MCP Streamable HTTP transport specification.
+ Detects the server's protocol era on first use.
+ """
+ if self.era is None:
+ await self.initialize()
+ if self.era is MCPProtocolEra.MODERN:
+ return await self._send_modern(method, params)
+ return await self._send_legacy(method, params)
+
async def discover_auth(self) -> dict[str, Any] | None:
"""Probe the MCP server's OAuth metadata (RFC 9728 / MCP spec).
@@ -280,80 +714,74 @@ class MCPClient:
async def discover_auth_server_metadata(
self, auth_server_url: str
- ) -> dict[str, Any] | None:
+ ) -> tuple[dict[str, Any], str] | None:
"""Fetch the OAuth Authorization Server Metadata (RFC 8414).
- Given an authorization server URL, returns a dict with:
- - ``authorization_endpoint``
- - ``token_endpoint``
- - ``registration_endpoint`` (for dynamic client registration)
- - ``scopes_supported``
- - ``code_challenge_methods_supported``
- - etc.
+ Given an authorization server URL, returns the metadata dict, which
+ holds ``authorization_endpoint``, ``token_endpoint``,
+ ``registration_endpoint`` (for dynamic client registration),
+ ``scopes_supported``, ``code_challenge_methods_supported`` and so on,
+ paired with the issuer identifier that document is *required* to
+ declare.
+
+ RFC 8414 §3.3 ties the two together: the ``issuer`` in the document
+ must be the URL the document was fetched for, minus the well-known
+ path segment. Which of the candidate URLs below answered therefore
+ decides the expected issuer, and only the caller comparing against
+ that exact value can tell a tenant apart from its own origin.
"""
from urllib.parse import urlparse
parsed = urlparse(auth_server_url)
- base = f"{parsed.scheme}://{parsed.netloc}"
+ base = f"{parsed.scheme.lower()}://{parsed.netloc.lower()}"
path = parsed.path.rstrip("/")
- # Try standard metadata endpoints (RFC 8414 and OpenID Connect)
+ # Try standard metadata endpoints (RFC 8414 and OpenID Connect), each
+ # paired with the issuer a document served there must declare.
candidates = []
if path and path != "/":
- candidates.append(f"{base}/.well-known/oauth-authorization-server{path}")
- candidates.append(f"{base}/.well-known/oauth-authorization-server")
- candidates.append(f"{base}/.well-known/openid-configuration")
+ candidates.append(
+ (
+ f"{base}/.well-known/oauth-authorization-server{path}",
+ f"{base}{path}",
+ )
+ )
+ candidates.append((f"{base}/.well-known/oauth-authorization-server", base))
+ candidates.append((f"{base}/.well-known/openid-configuration", base))
requests = Requests(
raise_for_status=False,
)
- for url in candidates:
+ for url, expected_issuer in candidates:
try:
resp = await requests.get(url)
if resp.status == 200:
data = resp.json()
if isinstance(data, dict) and "authorization_endpoint" in data:
- return data
+ return data, expected_issuer
except Exception:
continue
return None
- async def initialize(self) -> dict[str, Any]:
- """
- Send the MCP initialize request.
-
- This is required by the MCP protocol before any other requests.
- Returns the server's capabilities.
- """
- result = await self._send_request(
- "initialize",
- {
- "protocolVersion": "2025-03-26",
- "capabilities": {},
- "clientInfo": {"name": "AutoGPT-Platform", "version": "1.0.0"},
- },
- )
- # Send initialized notification (no response expected)
- await self._send_notification("notifications/initialized")
-
- return result or {}
-
async def close(self) -> None:
- """Terminate the MCP session on the server (Streamable HTTP spec).
-
- The MCP transport spec asks clients to ``DELETE`` the session URL
- with their ``Mcp-Session-Id`` header so the server can free its
- session state immediately instead of waiting for a timeout sweep.
- Best-effort: failures are swallowed so a flaky close can't poison
- the caller's flow. Resets ``self._session_id`` so a subsequent
- ``initialize`` starts a fresh session.
+ """Release server-side state, if the protocol era has any.
+
+ Legacy servers may have minted an ``Mcp-Session-Id``; the transport
+ spec asks clients to ``DELETE`` the session URL so the server can free
+ it immediately instead of waiting for a timeout sweep. Modern servers
+ are stateless, so there is nothing to release. Best-effort: failures
+ are swallowed so a flaky close can't poison the caller's flow.
"""
if not self._session_id:
return
try:
headers = self._build_headers()
- requests = Requests(raise_for_status=False, extra_headers=headers)
+ requests = Requests(
+ raise_for_status=False,
+ retry_max_attempts=_HTTP_RETRY_ATTEMPTS,
+ extra_headers=headers,
+ )
await requests.delete(self.server_url)
except Exception:
pass
@@ -365,6 +793,8 @@ class MCPClient:
Discover available tools from the MCP server.
Returns a list of MCPTool objects with name, description, and input schema.
+ On modern servers, tools whose ``x-mcp-header`` annotations are invalid
+ are dropped (and logged), as the transport spec requires.
"""
result = await self._send_request("tools/list")
if not result or "tools" not in result:
@@ -372,17 +802,74 @@ class MCPClient:
tools = []
for tool_data in result["tools"]:
+ name = tool_data.get("name", "")
+ input_schema = tool_data.get("inputSchema", {})
+ if self.era is MCPProtocolEra.MODERN:
+ try:
+ self._header_params[name] = collect_header_params(input_schema)
+ except InvalidHeaderAnnotation as e:
+ logger.warning(
+ "Dropping MCP tool %r from %s: invalid x-mcp-header (%s)",
+ name,
+ self.server_url,
+ e,
+ )
+ self._header_params.pop(name, None)
+ continue
tools.append(
MCPTool(
- name=tool_data.get("name", ""),
- description=tool_data.get("description", ""),
- input_schema=tool_data.get("inputSchema", {}),
+ name=name,
+ # ``or ""``: a server may send an explicit ``null`` rather
+ # than omitting the key, and the model requires a string.
+ description=tool_data.get("description") or "",
+ input_schema=input_schema,
)
)
return tools
+ def _content_blocks(self, raw: Any) -> list[dict[str, Any]]:
+ """Content blocks from a ``tools/call`` result, tolerating sloppy servers.
+
+ Every item is an object per the spec. A bare scalar would fail model
+ validation and take the whole call down, so wrap it as a text block
+ instead; ``parse_mcp_content`` then reads it the same way.
+ """
+ if not isinstance(raw, list):
+ return []
+ blocks: list[dict[str, Any]] = []
+ for item in raw:
+ if isinstance(item, dict):
+ blocks.append(item)
+ else:
+ logger.warning(
+ "MCP server %s returned a %s content item, not an object; "
+ "treating it as text",
+ self.server_url,
+ type(item).__name__,
+ )
+ blocks.append({"type": "text", "text": str(item)})
+ return blocks
+
+ @staticmethod
+ def _header_params_from_schema(
+ tool_name: str, input_schema: dict[str, Any]
+ ) -> list[HeaderParam]:
+ try:
+ return collect_header_params(input_schema)
+ except InvalidHeaderAnnotation as e:
+ # The same rule that drops the tool from ``list_tools``: a
+ # spec-violating annotation makes the tool uncallable.
+ raise MCPClientError(
+ f"MCP tool '{tool_name}' has an invalid x-mcp-header "
+ f"annotation and cannot be called: {e}"
+ ) from e
+
async def call_tool(
- self, tool_name: str, arguments: dict[str, Any]
+ self,
+ tool_name: str,
+ arguments: dict[str, Any],
+ *,
+ input_schema: dict[str, Any] | None = None,
) -> MCPCallResult:
"""
Call a tool on the MCP server.
@@ -390,18 +877,54 @@ class MCPClient:
Args:
tool_name: The name of the tool to call.
arguments: The arguments to pass to the tool.
+ input_schema: The tool's input schema, if the caller has it. Lets
+ the client mirror ``x-mcp-header`` parameters into headers
+ without an extra ``tools/list`` round-trip.
Returns:
MCPCallResult with the tool's response content.
"""
- result = await self._send_request(
- "tools/call",
- {"name": tool_name, "arguments": arguments},
- )
+ if input_schema is not None and tool_name not in self._header_params:
+ if self.era is None:
+ await self.initialize()
+ if self.era is MCPProtocolEra.MODERN:
+ self._header_params[tool_name] = self._header_params_from_schema(
+ tool_name, input_schema
+ )
+
+ params: dict[str, Any] = {"name": tool_name, "arguments": arguments}
+ result = await self._send_request("tools/call", params)
+
+ # Multi Round-Trip Requests: a modern server may hand back an interim
+ # result. We declare no elicitation/sampling/roots capability, so a
+ # compliant server only ever asks us to echo ``requestState``.
+ round_trips = 0
+ while (
+ isinstance(result, dict)
+ and result.get("resultType") == RESULT_TYPE_INPUT_REQUIRED
+ ):
+ if result.get("inputRequests"):
+ raise MCPClientError(
+ f"MCP tool '{tool_name}' requires interactive input "
+ "(elicitation/sampling) mid-execution, which is not "
+ "supported yet"
+ )
+ if round_trips >= _MAX_INPUT_REQUIRED_RETRIES:
+ raise MCPClientError(
+ f"MCP tool '{tool_name}' kept requesting more input after "
+ f"{_MAX_INPUT_REQUIRED_RETRIES} extra round-trips; the "
+ "server may already have applied its side effects"
+ )
+ round_trips += 1
+ retry_params = dict(params)
+ if "requestState" in result:
+ retry_params["requestState"] = result["requestState"]
+ result = await self._send_request("tools/call", retry_params)
+
if not result:
return MCPCallResult(is_error=True)
return MCPCallResult(
- content=result.get("content", []),
- is_error=result.get("isError", False),
+ content=self._content_blocks(result.get("content")),
+ is_error=bool(result.get("isError", False)),
)
diff --git a/autogpt_platform/backend/backend/blocks/mcp/conftest.py b/autogpt_platform/backend/backend/blocks/mcp/conftest.py
new file mode 100644
index 0000000000..4338b6d282
--- /dev/null
+++ b/autogpt_platform/backend/backend/blocks/mcp/conftest.py
@@ -0,0 +1,11 @@
+import pytest
+
+from backend.blocks.mcp.protocol import era_cache
+
+
[email protected](autouse=True)
+def _fresh_era_cache():
+ """Era detection is cached per process; keep tests independent of order."""
+ era_cache.clear()
+ yield
+ era_cache.clear()
diff --git a/autogpt_platform/backend/backend/blocks/mcp/protocol.py b/autogpt_platform/backend/backend/blocks/mcp/protocol.py
new file mode 100644
index 0000000000..2e6e855e8f
--- /dev/null
+++ b/autogpt_platform/backend/backend/blocks/mcp/protocol.py
@@ -0,0 +1,392 @@
+"""
+MCP protocol-version helpers shared by the client and its tests.
+
+The client speaks two *eras* of the Model Context Protocol:
+
+* **Legacy** (``2025-03-26`` … ``2025-11-25``): an ``initialize`` handshake
+ establishes a session; the server may mint an ``Mcp-Session-Id`` that is
+ echoed on every later request and released with HTTP ``DELETE``.
+* **Modern** (``2026-07-28`` and later): stateless. Every request carries its
+ protocol version, client identity and capabilities in ``params._meta`` and
+ mirrors the method / target name into ``Mcp-Method`` / ``Mcp-Name`` headers so
+ intermediaries can route without parsing the body.
+
+Reference: https://modelcontextprotocol.io/specification/2026-07-28
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import re
+import threading
+import time
+from collections import OrderedDict
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+LEGACY_PROTOCOL_VERSION = "2025-03-26"
+MODERN_PROTOCOL_VERSION = "2026-07-28"
+# Modern versions we can speak, newest first. Extend when a newer revision is
+# implemented; version negotiation picks the first entry the server also lists.
+SUPPORTED_MODERN_VERSIONS: tuple[str, ...] = (MODERN_PROTOCOL_VERSION,)
+
+CLIENT_INFO: dict[str, str] = {"name": "AutoGPT-Platform", "version": "1.0.0"}
+# We do not implement elicitation, sampling or roots, so a compliant modern
+# server must never send us ``inputRequests`` (MRTR). Declaring nothing is
+# what makes that guarantee hold.
+CLIENT_CAPABILITIES: dict[str, Any] = {}
+
+META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion"
+META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo"
+META_CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities"
+META_SERVER_INFO = "io.modelcontextprotocol/serverInfo"
+
+HEADER_PROTOCOL_VERSION = "MCP-Protocol-Version"
+HEADER_METHOD = "Mcp-Method"
+HEADER_NAME = "Mcp-Name"
+HEADER_PARAM_PREFIX = "Mcp-Param-"
+HEADER_SESSION_ID = "Mcp-Session-Id"
+
+# JSON-RPC error codes reserved by the 2026-07-28 specification. Receiving any
+# of these proves the peer is a modern server, even on an HTTP 400.
+ERROR_HEADER_MISMATCH = -32020
+ERROR_MISSING_CLIENT_CAPABILITY = -32021
+ERROR_UNSUPPORTED_PROTOCOL_VERSION = -32022
+MODERN_ERROR_CODES = frozenset(
+ {
+ ERROR_HEADER_MISMATCH,
+ ERROR_MISSING_CLIENT_CAPABILITY,
+ ERROR_UNSUPPORTED_PROTOCOL_VERSION,
+ }
+)
+ERROR_METHOD_NOT_FOUND = -32601
+ERROR_INVALID_PARAMS = -32602
+
+RESULT_TYPE_COMPLETE = "complete"
+RESULT_TYPE_INPUT_REQUIRED = "input_required"
+
+# Methods whose ``params.name`` / ``params.uri`` must be mirrored into Mcp-Name.
+_NAME_SOURCE_FIELD: dict[str, str] = {
+ "tools/call": "name",
+ "prompts/get": "name",
+ "resources/read": "uri",
+}
+
+
+class MCPProtocolEra(str, Enum):
+ LEGACY = "legacy"
+ MODERN = "modern"
+
+
+# ────────────────────────────── era cache ──────────────────────────────
+
+
+class MCPServerProtocol(BaseModel):
+ """What we last learned about a server: its era and negotiated version."""
+
+ model_config = ConfigDict(frozen=True)
+
+ era: MCPProtocolEra
+ protocol_version: str
+
+
+class MCPServerEraCache:
+ """Remember which era each MCP server speaks.
+
+ The spec asks clients to cache era detection per origin so a legacy server
+ does not pay for a failed modern probe on every connection. Entries
+ expire so a server that upgrades is picked up without a restart, and
+ callers drop an entry as soon as its assumption fails.
+
+ In-memory and per process on purpose: the cost of a miss is one extra
+ round-trip, which is not worth a cross-process dependency. Keys are
+ user-supplied URLs, so the cache is bounded: once full, the least
+ recently used entry is evicted.
+ """
+
+ def __init__(self, ttl_seconds: float = 3600.0, max_entries: int = 1024):
+ self.ttl_seconds = ttl_seconds
+ self.max_entries = max_entries
+ self._entries: OrderedDict[str, tuple[MCPServerProtocol, float]] = OrderedDict()
+ self._lock = threading.Lock()
+
+ def __len__(self) -> int:
+ with self._lock:
+ return len(self._entries)
+
+ def get(self, server_url: str) -> MCPServerProtocol | None:
+ with self._lock:
+ entry = self._entries.get(server_url)
+ if entry is None:
+ return None
+ value, expires_at = entry
+ if expires_at <= time.monotonic():
+ del self._entries[server_url]
+ return None
+ self._entries.move_to_end(server_url)
+ return value
+
+ def set(self, server_url: str, value: MCPServerProtocol) -> None:
+ with self._lock:
+ self._entries[server_url] = (value, time.monotonic() + self.ttl_seconds)
+ self._entries.move_to_end(server_url)
+ while len(self._entries) > self.max_entries:
+ self._entries.popitem(last=False)
+
+ def forget(self, server_url: str) -> None:
+ with self._lock:
+ self._entries.pop(server_url, None)
+
+ def clear(self) -> None:
+ with self._lock:
+ self._entries.clear()
+
+
+era_cache = MCPServerEraCache()
+
+
+# ─────────────────────────── request metadata ───────────────────────────
+
+
+def build_request_meta(protocol_version: str) -> dict[str, Any]:
+ """The ``_meta`` block every modern request must carry."""
+ return {
+ META_PROTOCOL_VERSION: protocol_version,
+ META_CLIENT_INFO: dict(CLIENT_INFO),
+ META_CLIENT_CAPABILITIES: dict(CLIENT_CAPABILITIES),
+ }
+
+
+def negotiate_version(supported_by_server: Any) -> str | None:
+ """Pick the newest version both sides speak, or ``None`` if there is none."""
+ if not isinstance(supported_by_server, list):
+ return None
+ offered = {v for v in supported_by_server if isinstance(v, str)}
+ for candidate in SUPPORTED_MODERN_VERSIONS:
+ if candidate in offered:
+ return candidate
+ return None
+
+
+def is_modern_jsonrpc_error(body: Any) -> bool:
+ """True if *body* is a JSON-RPC error whose code the modern spec reserves."""
+ if not isinstance(body, dict):
+ return False
+ error = body.get("error")
+ return isinstance(error, dict) and error.get("code") in MODERN_ERROR_CODES
+
+
+def jsonrpc_error_code(body: Any) -> int | None:
+ if not isinstance(body, dict):
+ return None
+ error = body.get("error")
+ if not isinstance(error, dict):
+ return None
+ code = error.get("code")
+ return code if isinstance(code, int) else None
+
+
+# ─────────────────────────── header encoding ───────────────────────────
+
+_BASE64_SENTINEL_PREFIX = "=?base64?"
+_BASE64_SENTINEL_SUFFIX = "?="
+
+
+def encode_header_value(value: str) -> str:
+ """Encode a body value for an ``Mcp-Name`` / ``Mcp-Param-*`` header.
+
+ Plain visible-ASCII values travel as-is. Anything else (non-ASCII,
+ control characters, leading/trailing whitespace, or a value that already
+ looks like the sentinel) is Base64-wrapped as ``=?base64?…?=`` so it
+ cannot be misread or used for header injection.
+ """
+ plain = all(0x20 <= ord(ch) <= 0x7E for ch in value)
+ padded = value != value.strip()
+ looks_encoded = value.startswith(_BASE64_SENTINEL_PREFIX) and value.endswith(
+ _BASE64_SENTINEL_SUFFIX
+ )
+ if plain and not padded and not looks_encoded:
+ return value
+ encoded = base64.b64encode(value.encode("utf-8")).decode("ascii")
+ return f"{_BASE64_SENTINEL_PREFIX}{encoded}{_BASE64_SENTINEL_SUFFIX}"
+
+
+def decode_header_value(value: str) -> str:
+ """Inverse of :func:`encode_header_value` (used by the test server)."""
+ if value.startswith(_BASE64_SENTINEL_PREFIX) and value.endswith(
+ _BASE64_SENTINEL_SUFFIX
+ ):
+ inner = value[len(_BASE64_SENTINEL_PREFIX) : -len(_BASE64_SENTINEL_SUFFIX)]
+ try:
+ return base64.b64decode(inner, validate=True).decode("utf-8")
+ except (binascii.Error, UnicodeDecodeError):
+ return value
+ return value
+
+
+def name_header_for(method: str, params: dict[str, Any] | None) -> str | None:
+ """Value for ``Mcp-Name`` on *method*, or ``None`` when it is not required."""
+ field = _NAME_SOURCE_FIELD.get(method)
+ if field is None or not params:
+ return None
+ value = params.get(field)
+ if not isinstance(value, str):
+ return None
+ return encode_header_value(value)
+
+
+# ─────────────────────────── x-mcp-header ───────────────────────────
+
+# RFC 7230 ``tchar``; matched with ``fullmatch`` so a trailing newline fails.
+_TCHAR_RE = re.compile(r"[!#$%&'*+\-.^_`|~0-9A-Za-z]+")
+_HEADER_PARAM_TYPES = {"string", "integer", "boolean"}
+_SAFE_INT_MIN = -(2**53) + 1
+_SAFE_INT_MAX = 2**53 - 1
+_HEADER_PARAM_PROPERTY = "x-mcp-header"
+# JSON Schema keywords whose values are *instance data*, not subschemas. A
+# ``default``/``const``/``enum``/``examples`` value may legitimately be an
+# object carrying an ``x-mcp-header`` key (a tool that takes a schema as an
+# argument, say); that is payload, not an annotation, so the walk below must
+# not read it as one.
+_SCHEMA_INSTANCE_VALUE_KEYS = frozenset(
+ {"default", "const", "enum", "examples", "example"}
+)
+
+
+class HeaderParam(BaseModel):
+ """A tool parameter the server asked us to mirror into a header."""
+
+ model_config = ConfigDict(frozen=True)
+
+ path: tuple[str, ...]
+ header_name: str
+ json_type: str
+
+
+class InvalidHeaderAnnotation(ValueError):
+ """A tool's ``x-mcp-header`` annotations violate the spec."""
+
+
+def collect_header_params(input_schema: Any) -> list[HeaderParam]:
+ """Find every ``x-mcp-header`` annotation reachable through ``properties``.
+
+ Raises :class:`InvalidHeaderAnnotation` if any annotation breaks the spec's
+ constraints; callers must then drop the whole tool from ``tools/list``.
+ """
+ found: list[HeaderParam] = []
+ seen_names: set[str] = set()
+
+ def walk(schema: Any, path: tuple[str, ...]) -> None:
+ if not isinstance(schema, dict):
+ return
+ # Presence, not truthiness: an explicit ``null`` is a malformed
+ # annotation and must invalidate the tool, not be ignored.
+ if _HEADER_PARAM_PROPERTY in schema:
+ annotation = schema[_HEADER_PARAM_PROPERTY]
+ if not path:
+ raise InvalidHeaderAnnotation(
+ "x-mcp-header is not allowed on the root schema"
+ )
+ _validate_annotation(annotation, schema, path, seen_names)
+ found.append(
+ HeaderParam(path=path, header_name=annotation, json_type=schema["type"])
+ )
+ properties = schema.get("properties")
+ if isinstance(properties, dict):
+ for key, sub in properties.items():
+ walk(sub, path + (key,))
+
+ walk(input_schema, ())
+ _reject_unreachable_annotations(input_schema)
+ return found
+
+
+def _validate_annotation(
+ annotation: Any,
+ schema: dict[str, Any],
+ path: tuple[str, ...],
+ seen_names: set[str],
+) -> None:
+ where = ".".join(path)
+ if not isinstance(annotation, str) or not annotation:
+ raise InvalidHeaderAnnotation(
+ f"{where}: x-mcp-header must be a non-empty string"
+ )
+ if not _TCHAR_RE.fullmatch(annotation):
+ raise InvalidHeaderAnnotation(
+ f"{where}: x-mcp-header {annotation!r} is not a valid HTTP field name"
+ )
+ if schema.get("type") not in _HEADER_PARAM_TYPES:
+ raise InvalidHeaderAnnotation(
+ f"{where}: x-mcp-header is only allowed on string/integer/boolean "
+ f"parameters, got {schema.get('type')!r}"
+ )
+ folded = annotation.casefold()
+ if folded in seen_names:
+ raise InvalidHeaderAnnotation(
+ f"{where}: duplicate x-mcp-header name {annotation!r}"
+ )
+ seen_names.add(folded)
+
+
+def _reject_unreachable_annotations(schema: Any) -> None:
+ """An annotation behind ``items``/``oneOf``/``$ref``/… invalidates the tool."""
+
+ def walk(node: Any, reachable: bool) -> None:
+ if isinstance(node, dict):
+ if _HEADER_PARAM_PROPERTY in node and not reachable:
+ raise InvalidHeaderAnnotation(
+ "x-mcp-header must be statically reachable through "
+ "`properties` only"
+ )
+ for key, sub in node.items():
+ if key in _SCHEMA_INSTANCE_VALUE_KEYS:
+ continue
+ if key == "properties" and isinstance(sub, dict):
+ for child in sub.values():
+ walk(child, reachable)
+ elif isinstance(sub, (dict, list)):
+ walk(sub, False)
+ elif isinstance(node, list):
+ for item in node:
+ walk(item, False)
+
+ walk(schema, True)
+
+
+def extract_header_params(
+ header_params: list[HeaderParam], arguments: dict[str, Any] | None
+) -> dict[str, str]:
+ """Build ``Mcp-Param-*`` headers from call *arguments*.
+
+ Missing or ``null`` values are simply omitted, as the spec requires.
+ """
+ headers: dict[str, str] = {}
+ for param in header_params:
+ value: Any = arguments or {}
+ for key in param.path:
+ if not isinstance(value, dict) or key not in value:
+ value = None
+ break
+ value = value[key]
+ if value is None:
+ continue
+ if param.json_type == "boolean":
+ if not isinstance(value, bool):
+ continue
+ text = "true" if value else "false"
+ elif param.json_type == "integer":
+ if isinstance(value, bool) or not isinstance(value, int):
+ continue
+ if not _SAFE_INT_MIN <= value <= _SAFE_INT_MAX:
+ continue
+ text = str(value)
+ else:
+ if not isinstance(value, str):
+ continue
+ text = value
+ headers[f"{HEADER_PARAM_PREFIX}{param.header_name}"] = encode_header_value(text)
+ return headers
diff --git a/autogpt_platform/backend/backend/blocks/mcp/test_e2e.py b/autogpt_platform/backend/backend/blocks/mcp/test_e2e.py
index 7818fac9ce..b7dba97f00 100644
--- a/autogpt_platform/backend/backend/blocks/mcp/test_e2e.py
+++ b/autogpt_platform/backend/backend/blocks/mcp/test_e2e.py
@@ -14,6 +14,11 @@ import os
import pytest
from backend.blocks.mcp.client import MCPClient
+from backend.blocks.mcp.protocol import (
+ LEGACY_PROTOCOL_VERSION,
+ MODERN_PROTOCOL_VERSION,
+ MCPProtocolEra,
+)
# Public MCP server that requires no authentication
OPENAI_DOCS_MCP_URL = "https://developers.openai.com/mcp"
@@ -33,7 +38,15 @@ class TestRealMCPServer:
client = MCPClient(OPENAI_DOCS_MCP_URL)
result = await client.initialize()
- assert result["protocolVersion"] == "2025-03-26"
+ # A live server may upgrade at any time; whichever era it speaks, the
+ # negotiated version must be the one that belongs to that era.
+ expected_version = (
+ MODERN_PROTOCOL_VERSION
+ if client.era is MCPProtocolEra.MODERN
+ else LEGACY_PROTOCOL_VERSION
+ )
+ assert client.era is not None
+ assert result["protocolVersion"] == expected_version
assert "serverInfo" in result
assert result["serverInfo"]["name"] == "openai-docs-mcp"
assert "tools" in result.get("capabilities", {})
diff --git a/autogpt_platform/backend/backend/blocks/mcp/test_integration.py b/autogpt_platform/backend/backend/blocks/mcp/test_integration.py
index 601de28900..ecfd5cf810 100644
--- a/autogpt_platform/backend/backend/blocks/mcp/test_integration.py
+++ b/autogpt_platform/backend/backend/blocks/mcp/test_integration.py
@@ -15,8 +15,13 @@ from aiohttp import web
from pydantic import SecretStr
from backend.blocks.mcp.block import MCPToolBlock
-from backend.blocks.mcp.client import MCPClient
-from backend.blocks.mcp.test_server import create_test_mcp_app
+from backend.blocks.mcp.client import MCPClient, MCPClientError
+from backend.blocks.mcp.protocol import (
+ MODERN_PROTOCOL_VERSION,
+ MCPProtocolEra,
+ era_cache,
+)
+from backend.blocks.mcp.test_server import MODERN_EXTRA_TOOLS, create_test_mcp_app
from backend.data.model import OAuth2Credentials
MOCK_USER_ID = "test-user-integration"
@@ -28,8 +33,10 @@ class _MCPTestServer:
This avoids event loop conflicts with pytest-asyncio.
"""
- def __init__(self, auth_token: str | None = None):
+ def __init__(self, auth_token: str | None = None, **app_options):
self.auth_token = auth_token
+ self.app_options = app_options
+ self.app: web.Application | None = None
self.url: str = ""
self._runner: web.AppRunner | None = None
self._loop: asyncio.AbstractEventLoop | None = None
@@ -44,7 +51,8 @@ class _MCPTestServer:
self._loop.run_forever()
async def _start(self):
- app = create_test_mcp_app(auth_token=self.auth_token)
+ app = create_test_mcp_app(auth_token=self.auth_token, **self.app_options)
+ self.app = app
self._runner = web.AppRunner(app)
await self._runner.setup()
site = web.TCPSite(self._runner, "127.0.0.1", 0)
@@ -59,6 +67,21 @@ class _MCPTestServer:
raise RuntimeError("MCP test server failed to start within 5 seconds")
return self
+ @property
+ def requests(self) -> list[dict]:
+ assert self.app is not None
+ return self.app["requests"]
+
+ @property
+ def sessions(self) -> set[str]:
+ assert self.app is not None
+ return self.app["sessions"]
+
+ @property
+ def deleted_sessions(self) -> list[str]:
+ assert self.app is not None
+ return self.app["deleted_sessions"]
+
def stop(self):
if self._loop and self._runner:
asyncio.run_coroutine_threadsafe(self._runner.cleanup(), self._loop).result(
@@ -388,3 +411,239 @@ class TestMCPToolBlockIntegration:
assert len(outputs) == 1
assert outputs[0][0] == "result"
assert outputs[0][1] == "No auth needed"
+
+
+# ── Protocol-era integration tests ───────────────────────────────────
+
+
+def _server(**kwargs) -> _MCPTestServer:
+ server = _MCPTestServer(**kwargs)
+ server.start()
+ return server
+
+
[email protected](scope="module")
+def modern_server():
+ server = _server(era="modern")
+ yield server
+ server.stop()
+
+
[email protected](scope="module")
+def modern_sse_server():
+ server = _server(era="modern", sse=True)
+ yield server
+ server.stop()
+
+
[email protected](scope="module")
+def dual_server():
+ server = _server(era="dual", sessions=True)
+ yield server
+ server.stop()
+
+
[email protected](scope="module")
+def session_legacy_server():
+ server = _server(era="legacy", sessions=True)
+ yield server
+ server.stop()
+
+
[email protected](scope="module")
+def incompatible_modern_server():
+ server = _server(era="modern", supported_versions=("2099-01-01",))
+ yield server
+ server.stop()
+
+
+class TestProtocolEras:
+ """The same client against legacy, modern and dual-era servers."""
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_modern_server_is_used_statelessly(self, modern_server):
+ before = len(modern_server.requests)
+ client = _make_client(modern_server.url)
+ result = await client.initialize()
+
+ assert client.era is MCPProtocolEra.MODERN
+ assert result["protocolVersion"] == MODERN_PROTOCOL_VERSION
+ assert result["serverInfo"]["name"] == "test-mcp-server"
+ assert "tools" in result["capabilities"]
+
+ tools = await client.list_tools()
+ names = {t.name for t in tools}
+ # broken_header_tool carries an invalid x-mcp-header and must be dropped
+ assert names == {
+ "get_weather",
+ "add_numbers",
+ "echo",
+ "execute_sql",
+ "needs_confirmation",
+ "needs_elicitation",
+ }
+
+ result = await client.call_tool("get_weather", {"city": "Oslo"})
+ assert not result.is_error
+ assert json.loads(result.content[0]["text"])["city"] == "Oslo"
+
+ requests = modern_server.requests[before:]
+ methods = [r["method"] for r in requests]
+ assert "initialize" not in methods
+ assert "notifications/initialized" not in methods
+ call = next(r for r in requests if r["method"] == "tools/call")
+ assert call["headers"]["Mcp-Method"] == "tools/call"
+ assert call["headers"]["Mcp-Name"] == "get_weather"
+ assert call["headers"]["MCP-Protocol-Version"] == MODERN_PROTOCOL_VERSION
+ assert "Mcp-Session-Id" not in call["headers"]
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_modern_server_over_sse(self, modern_sse_server):
+ client = _make_client(modern_sse_server.url)
+ await client.initialize()
+ assert client.era is MCPProtocolEra.MODERN
+ result = await client.call_tool("echo", {"message": "hi"})
+ assert result.content[0]["text"] == "hi"
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_legacy_fallback_from_method_not_found(self, mcp_server):
+ client = _make_client(mcp_server)
+ result = await client.initialize()
+ assert client.era is MCPProtocolEra.LEGACY
+ assert result["protocolVersion"] == "2025-03-26"
+ cached = era_cache.get(client.server_url)
+ assert cached is not None and cached.era is MCPProtocolEra.LEGACY
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_legacy_fallback_from_plain_400(self, session_legacy_server):
+ before = len(session_legacy_server.requests)
+ client = _make_client(session_legacy_server.url)
+ await client.initialize()
+ assert client.era is MCPProtocolEra.LEGACY
+ tools = await client.list_tools()
+ assert len(tools) == 3
+ methods = [r["method"] for r in session_legacy_server.requests[before:]]
+ assert methods[:2] == ["server/discover", "initialize"]
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_cached_era_skips_probe_on_next_connection(
+ self, session_legacy_server
+ ):
+ first = _make_client(session_legacy_server.url)
+ await first.initialize()
+ before = len(session_legacy_server.requests)
+
+ second = _make_client(session_legacy_server.url)
+ await second.initialize()
+ new_methods = [r["method"] for r in session_legacy_server.requests[before:]]
+ assert "server/discover" not in new_methods
+ assert new_methods[0] == "initialize"
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_dual_server_prefers_modern(self, dual_server):
+ client = _make_client(dual_server.url)
+ await client.initialize()
+ assert client.era is MCPProtocolEra.MODERN
+ result = await client.call_tool("add_numbers", {"a": 1, "b": 2})
+ assert json.loads(result.content[0]["text"])["result"] == 3
+ assert not dual_server.sessions
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_legacy_sessions_are_echoed_and_released(self, session_legacy_server):
+ client = _make_client(session_legacy_server.url)
+ await client.initialize()
+ assert client.era is MCPProtocolEra.LEGACY
+ assert client._session_id
+ tools = await client.list_tools()
+ assert len(tools) == 3
+ session_id = client._session_id
+ await client.close()
+ assert session_id in session_legacy_server.deleted_sessions
+ assert client._session_id is None
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_x_mcp_header_is_mirrored(self, modern_server):
+ client = _make_client(modern_server.url)
+ await client.initialize()
+ await client.list_tools()
+ before = len(modern_server.requests)
+ result = await client.call_tool(
+ "execute_sql", {"region": "eu-west", "query": "select 1"}
+ )
+ assert not result.is_error
+ calls = [
+ r for r in modern_server.requests[before:] if r["method"] == "tools/call"
+ ]
+ assert len(calls) == 1
+ assert calls[0]["headers"]["Mcp-Param-Region"] == "eu-west"
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_known_schema_avoids_header_mismatch_round_trip(self, modern_server):
+ client = _make_client(modern_server.url)
+ await client.initialize()
+ schema = next(
+ t["inputSchema"] for t in MODERN_EXTRA_TOOLS if t["name"] == "execute_sql"
+ )
+ before = len(modern_server.requests)
+ result = await client.call_tool(
+ "execute_sql",
+ {"region": "us-east", "query": "select 1"},
+ input_schema=schema,
+ )
+ assert not result.is_error
+ methods = [r["method"] for r in modern_server.requests[before:]]
+ assert methods == ["tools/call"]
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_header_mismatch_recovers_without_prior_list(self, modern_server):
+ client = _make_client(modern_server.url)
+ await client.initialize()
+ before = len(modern_server.requests)
+ result = await client.call_tool(
+ "execute_sql", {"region": "ap-south", "query": "select 1"}
+ )
+ assert not result.is_error
+ methods = [r["method"] for r in modern_server.requests[before:]]
+ assert methods == ["tools/call", "tools/list", "tools/call"]
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_input_required_request_state_round_trip(self, modern_server):
+ client = _make_client(modern_server.url)
+ await client.initialize()
+ result = await client.call_tool("needs_confirmation", {})
+ assert result.content[0]["text"] == "confirmed"
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_input_requests_are_reported(self, modern_server):
+ client = _make_client(modern_server.url)
+ await client.initialize()
+ with pytest.raises(MCPClientError, match="requires interactive input"):
+ await client.call_tool("needs_elicitation", {})
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_incompatible_modern_server(self, incompatible_modern_server):
+ client = _make_client(incompatible_modern_server.url)
+ with pytest.raises(MCPClientError, match="does not support any protocol"):
+ await client.initialize()
+ assert era_cache.get(client.server_url) is None
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_block_full_flow_against_modern_server(self, modern_server):
+ block = MCPToolBlock()
+ input_data = MCPToolBlock.Input(
+ server_url=modern_server.url,
+ selected_tool="get_weather",
+ tool_input_schema={
+ "type": "object",
+ "properties": {"city": {"type": "string"}},
+ "required": ["city"],
+ },
+ tool_arguments={"city": "Paris"},
+ )
+
+ outputs = []
+ async for name, data in block.run(input_data, user_id=MOCK_USER_ID):
+ outputs.append((name, data))
+
+ assert outputs[0][0] == "result"
+ assert outputs[0][1]["city"] == "Paris"
diff --git a/autogpt_platform/backend/backend/blocks/mcp/test_mcp.py b/autogpt_platform/backend/backend/blocks/mcp/test_mcp.py
index d0a5632b85..7871b521df 100644
--- a/autogpt_platform/backend/backend/blocks/mcp/test_mcp.py
+++ b/autogpt_platform/backend/backend/blocks/mcp/test_mcp.py
@@ -9,6 +9,7 @@ import pytest
from backend.blocks.mcp.block import MCPToolBlock
from backend.blocks.mcp.client import MCPCallResult, MCPClient, MCPClientError
+from backend.blocks.mcp.protocol import MCPProtocolEra
from backend.util.test import execute_block_test
# ── SSE parsing unit tests ───────────────────────────────────────────
@@ -241,7 +242,8 @@ class TestMCPClient:
assert result.is_error
@pytest.mark.asyncio(loop_scope="session")
- async def test_initialize(self):
+ async def test_initialize_legacy(self):
+ """A server that rejects the modern probe gets the legacy handshake."""
client = MCPClient("https://mcp.example.com")
mock_result = {
@@ -251,14 +253,54 @@ class TestMCPClient:
}
with (
- patch.object(client, "_send_request", return_value=mock_result) as mock_req,
+ patch.object(client, "_probe_modern", return_value=None),
+ patch.object(client, "_send_legacy", return_value=mock_result) as mock_req,
patch.object(client, "_send_notification") as mock_notif,
):
result = await client.initialize()
mock_req.assert_called_once()
+ assert mock_req.call_args.args[0] == "initialize"
+ assert mock_req.call_args.args[1]["protocolVersion"] == "2025-03-26"
mock_notif.assert_called_once_with("notifications/initialized")
assert result["protocolVersion"] == "2025-03-26"
+ assert client.era is MCPProtocolEra.LEGACY
+ assert client.protocol_version == "2025-03-26"
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_initialize_modern(self):
+ """A server answering server/discover is used statelessly."""
+ client = MCPClient("https://mcp.example.com")
+
+ discover_result = {
+ "resultType": "complete",
+ "supportedVersions": ["2026-07-28"],
+ "capabilities": {"tools": {}},
+ "_meta": {
+ "io.modelcontextprotocol/serverInfo": {
+ "name": "modern-server",
+ "version": "2.0.0",
+ }
+ },
+ }
+
+ async def fake_probe():
+ client.protocol_version = "2026-07-28"
+ return discover_result
+
+ with (
+ patch.object(client, "_probe_modern", side_effect=fake_probe),
+ patch.object(client, "_send_legacy") as mock_legacy,
+ patch.object(client, "_send_notification") as mock_notif,
+ ):
+ result = await client.initialize()
+
+ mock_legacy.assert_not_called()
+ mock_notif.assert_not_called()
+ assert client.era is MCPProtocolEra.MODERN
+ assert result["protocolVersion"] == "2026-07-28"
+ assert result["serverInfo"]["name"] == "modern-server"
+ assert result["capabilities"] == {"tools": {}}
# ── MCPToolBlock unit tests ──────────────────────────────────────────
@@ -414,6 +456,44 @@ class TestMCPToolBlock:
assert outputs[0][0] == "error"
assert "Tool not found" in outputs[0][1]
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_call_mcp_tool_closes_client_when_call_fails(self):
+ block = MCPToolBlock()
+
+ with (
+ patch.object(MCPClient, "initialize", AsyncMock(return_value={})),
+ patch.object(
+ MCPClient,
+ "call_tool",
+ AsyncMock(side_effect=MCPClientError("boom")),
+ ),
+ patch.object(MCPClient, "close", AsyncMock()) as mock_close,
+ ):
+ with pytest.raises(MCPClientError, match="boom"):
+ await block._call_mcp_tool("https://mcp.example.com", "tool", {})
+
+ mock_close.assert_awaited_once()
+
+ @pytest.mark.asyncio(loop_scope="session")
+ async def test_call_mcp_tool_forwards_input_schema(self):
+ block = MCPToolBlock()
+ schema = {"type": "object", "properties": {"x": {"type": "string"}}}
+ call_tool = AsyncMock(
+ return_value=MCPCallResult(content=[{"type": "text", "text": "ok"}])
+ )
+
+ with (
+ patch.object(MCPClient, "initialize", AsyncMock(return_value={})),
+ patch.object(MCPClient, "call_tool", call_tool),
+ patch.object(MCPClient, "close", AsyncMock()),
+ ):
+ result = await block._call_mcp_tool(
+ "https://mcp.example.com", "tool", {"x": "1"}, input_schema=schema
+ )
+
+ assert result == "ok"
+ call_tool.assert_awaited_once_with("tool", {"x": "1"}, input_schema=schema)
+
@pytest.mark.asyncio(loop_scope="session")
async def test_call_mcp_tool_parses_json_text(self):
block = MCPToolBlock()
@@ -428,7 +508,7 @@ class TestMCPToolBlock:
async def mock_init(self):
return {}
- async def mock_call(self, name, args):
+ async def mock_call(self, name, args, **kwargs):
return mock_result
with (
@@ -455,7 +535,7 @@ class TestMCPToolBlock:
async def mock_init(self):
return {}
- async def mock_call(self, name, args):
+ async def mock_call(self, name, args, **kwargs):
return mock_result
with (
@@ -483,7 +563,7 @@ class TestMCPToolBlock:
async def mock_init(self):
return {}
- async def mock_call(self, name, args):
+ async def mock_call(self, name, args, **kwargs):
return mock_result
with (
@@ -508,7 +588,7 @@ class TestMCPToolBlock:
async def mock_init(self):
return {}
- async def mock_call(self, name, args):
+ async def mock_call(self, name, args, **kwargs):
return mock_result
with (
@@ -536,7 +616,7 @@ class TestMCPToolBlock:
async def mock_init(self):
return {}
- async def mock_call(self, name, args):
+ async def mock_call(self, name, args, **kwargs):
return mock_result
with (
@@ -568,7 +648,9 @@ class TestMCPToolBlock:
captured_tokens: list[str | None] = []
- async def mock_call(server_url, tool_name, arguments, authorization=None):
+ async def mock_call(
+ server_url, tool_name, arguments, authorization=None, input_schema=None
+ ):
captured_tokens.append(authorization)
return "ok"
@@ -601,7 +683,9 @@ class TestMCPToolBlock:
captured_tokens: list[str | None] = []
- async def mock_call(server_url, tool_name, arguments, authorization=None):
+ async def mock_call(
+ server_url, tool_name, arguments, authorization=None, input_schema=None
+ ):
captured_tokens.append(authorization)
return "ok"
diff --git a/autogpt_platform/backend/backend/blocks/mcp/test_oauth.py b/autogpt_platform/backend/backend/blocks/mcp/test_oauth.py
index e9a42f68ea..1d704c8e2f 100644
--- a/autogpt_platform/backend/backend/blocks/mcp/test_oauth.py
+++ b/autogpt_platform/backend/backend/blocks/mcp/test_oauth.py
@@ -238,5 +238,11 @@ class TestMCPClientDiscovery:
)
assert result is not None
- assert result["authorization_endpoint"] == "https://auth.example.com/authorize"
- assert result["token_endpoint"] == "https://auth.example.com/token"
+ metadata, expected_issuer = result
+ assert (
+ metadata["authorization_endpoint"] == "https://auth.example.com/authorize"
+ )
+ assert metadata["token_endpoint"] == "https://auth.example.com/token"
+ # RFC 8414 §3.3: a document served at the well-known root must declare
+ # the bare origin as its issuer.
+ assert expected_issuer == "https://auth.example.com"
diff --git a/autogpt_platform/backend/backend/blocks/mcp/test_protocol.py b/autogpt_platform/backend/backend/blocks/mcp/test_protocol.py
new file mode 100644
index 0000000000..e3382965a8
--- /dev/null
+++ b/autogpt_platform/backend/backend/blocks/mcp/test_protocol.py
@@ -0,0 +1,1221 @@
+"""
+Unit tests for the MCP 2026-07-28 protocol helpers and the client's
+dual-era behaviour (era detection, version negotiation, header mirroring,
+MRTR handling). No network: HTTP replies are faked at ``MCPClient._post``.
+"""
+
+import base64
+import json
+from typing import Any
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from backend.blocks.mcp.client import MCPClient, MCPClientError
+from backend.blocks.mcp.protocol import (
+ ERROR_HEADER_MISMATCH,
+ ERROR_METHOD_NOT_FOUND,
+ ERROR_MISSING_CLIENT_CAPABILITY,
+ ERROR_UNSUPPORTED_PROTOCOL_VERSION,
+ HEADER_METHOD,
+ HEADER_NAME,
+ HEADER_PROTOCOL_VERSION,
+ HEADER_SESSION_ID,
+ LEGACY_PROTOCOL_VERSION,
+ META_CLIENT_CAPABILITIES,
+ META_CLIENT_INFO,
+ META_PROTOCOL_VERSION,
+ META_SERVER_INFO,
+ MODERN_PROTOCOL_VERSION,
+ HeaderParam,
+ InvalidHeaderAnnotation,
+ MCPProtocolEra,
+ MCPServerEraCache,
+ MCPServerProtocol,
+ build_request_meta,
+ collect_header_params,
+ decode_header_value,
+ encode_header_value,
+ era_cache,
+ extract_header_params,
+ is_modern_jsonrpc_error,
+ name_header_for,
+ negotiate_version,
+)
+from backend.util.request import HTTPClientError, HTTPServerError, Response
+
+SERVER_URL = "https://mcp.example.com/mcp"
+
+
+# ───────────────────────── header encoding ─────────────────────────
+
+
+class TestHeaderEncoding:
+ def test_plain_ascii_passthrough(self):
+ assert encode_header_value("us-west1") == "us-west1"
+
+ @pytest.mark.parametrize(
+ "raw",
+ ["Hello, 世界", " padded ", "line1\nline2", "=?base64?literal?=", "tab\tin"],
+ )
+ def test_unsafe_values_are_base64_wrapped(self, raw: str):
+ encoded = encode_header_value(raw)
+ assert encoded.startswith("=?base64?") and encoded.endswith("?=")
+ inner = encoded[len("=?base64?") : -2]
+ assert base64.b64decode(inner).decode() == raw
+ assert decode_header_value(encoded) == raw
+
+ def test_spec_example(self):
+ assert encode_header_value("Hello, 世界") == "=?base64?SGVsbG8sIOS4lueVjA==?="
+
+ def test_decode_leaves_plain_values(self):
+ assert decode_header_value("plain") == "plain"
+
+ def test_name_header_only_for_named_methods(self):
+ assert name_header_for("tools/call", {"name": "get_weather"}) == "get_weather"
+ assert name_header_for("resources/read", {"uri": "file:///a"}) == "file:///a"
+ assert name_header_for("tools/list", None) is None
+ assert name_header_for("server/discover", {"name": "x"}) is None
+
+
+# ───────────────────────── request metadata ─────────────────────────
+
+
+class TestRequestMeta:
+ def test_meta_has_required_fields(self):
+ meta = build_request_meta("2026-07-28")
+ assert meta[META_PROTOCOL_VERSION] == "2026-07-28"
+ assert meta[META_CLIENT_INFO]["name"] == "AutoGPT-Platform"
+ assert meta[META_CLIENT_CAPABILITIES] == {}
+
+ def test_negotiate_picks_shared_version(self):
+ assert negotiate_version(["2025-11-25", "2026-07-28"]) == "2026-07-28"
+ assert negotiate_version(["2025-11-25"]) is None
+ assert negotiate_version("2026-07-28") is None
+ assert negotiate_version(None) is None
+
+ def test_modern_error_detection(self):
+ assert is_modern_jsonrpc_error({"error": {"code": -32022}})
+ assert is_modern_jsonrpc_error({"error": {"code": -32020}})
+ assert not is_modern_jsonrpc_error({"error": {"code": -32601}})
+ assert not is_modern_jsonrpc_error({"result": {}})
+ assert not is_modern_jsonrpc_error(None)
+
+
+# ───────────────────────── x-mcp-header ─────────────────────────
+
+
+class TestHeaderParams:
+ def test_collects_reachable_annotations(self):
+ schema = {
+ "type": "object",
+ "properties": {
+ "region": {"type": "string", "x-mcp-header": "Region"},
+ "opts": {
+ "type": "object",
+ "properties": {
+ "retries": {"type": "integer", "x-mcp-header": "Retries"},
+ "dry": {"type": "boolean", "x-mcp-header": "Dry-Run"},
+ },
+ },
+ "query": {"type": "string"},
+ },
+ }
+ params = collect_header_params(schema)
+ assert params == [
+ HeaderParam(path=("region",), header_name="Region", json_type="string"),
+ HeaderParam(
+ path=("opts", "retries"), header_name="Retries", json_type="integer"
+ ),
+ HeaderParam(
+ path=("opts", "dry"), header_name="Dry-Run", json_type="boolean"
+ ),
+ ]
+
+ def test_extract_formats_and_omits_missing(self):
+ params = [
+ HeaderParam(path=("region",), header_name="Region", json_type="string"),
+ HeaderParam(
+ path=("opts", "retries"), header_name="Retries", json_type="integer"
+ ),
+ HeaderParam(
+ path=("opts", "dry"), header_name="Dry-Run", json_type="boolean"
+ ),
+ HeaderParam(path=("absent",), header_name="Absent", json_type="string"),
+ HeaderParam(path=("nul",), header_name="Nul", json_type="string"),
+ ]
+ headers = extract_header_params(
+ params,
+ {"region": "eu-west", "opts": {"retries": 3, "dry": False}, "nul": None},
+ )
+ assert headers == {
+ "Mcp-Param-Region": "eu-west",
+ "Mcp-Param-Retries": "3",
+ "Mcp-Param-Dry-Run": "false",
+ }
+
+ def test_extract_encodes_unsafe_values(self):
+ params = [
+ HeaderParam(path=("greeting",), header_name="Greeting", json_type="string")
+ ]
+ headers = extract_header_params(params, {"greeting": "Hello, 世界"})
+ assert headers["Mcp-Param-Greeting"] == "=?base64?SGVsbG8sIOS4lueVjA==?="
+
+ @pytest.mark.parametrize(
+ "schema",
+ [
+ # empty name
+ {"properties": {"a": {"type": "string", "x-mcp-header": ""}}},
+ # trailing newline (``$`` would accept it, ``fullmatch`` must not)
+ {"properties": {"a": {"type": "string", "x-mcp-header": "Region\n"}}},
+ # annotation on the root schema itself
+ {"type": "object", "x-mcp-header": "Root", "properties": {}},
+ {"type": "object", "x-mcp-header": None, "properties": {}},
+ # present but null
+ {"properties": {"a": {"type": "string", "x-mcp-header": None}}},
+ # invalid field-name characters
+ {"properties": {"a": {"type": "string", "x-mcp-header": "Bad Name"}}},
+ {"properties": {"a": {"type": "string", "x-mcp-header": "X\r\nY"}}},
+ # number is not allowed
+ {"properties": {"a": {"type": "number", "x-mcp-header": "A"}}},
+ # duplicate (case-insensitive)
+ {
+ "properties": {
+ "a": {"type": "string", "x-mcp-header": "Region"},
+ "b": {"type": "string", "x-mcp-header": "region"},
+ }
+ },
+ # behind items / composition / $ref
+ {
+ "properties": {
+ "a": {
+ "type": "array",
+ "items": {"type": "string", "x-mcp-header": "A"},
+ }
+ }
+ },
+ {"oneOf": [{"properties": {"a": {"type": "string", "x-mcp-header": "A"}}}]},
+ {"$defs": {"x": {"type": "string", "x-mcp-header": "A"}}},
+ ],
+ )
+ def test_invalid_annotations_are_rejected(self, schema: dict[str, Any]):
+ with pytest.raises(InvalidHeaderAnnotation):
+ collect_header_params(schema)
+
+ def test_schema_without_annotations(self):
+ assert collect_header_params({"type": "object", "properties": {}}) == []
+ assert collect_header_params(None) == []
+
+ @pytest.mark.parametrize(
+ "instance_keyword",
+ ["default", "const", "enum", "examples", "example"],
+ )
+ def test_annotation_inside_instance_data_is_not_an_annotation(
+ self, instance_keyword: str
+ ):
+ """``x-mcp-header`` in a value, not a schema, must not drop the tool.
+
+ A tool whose argument *is* a JSON Schema can legitimately carry an
+ ``x-mcp-header`` key inside a ``default``/``enum``/``examples`` value.
+ That is payload the server echoes back, not an annotation for us.
+ """
+ payload = {"x-mcp-header": "X-Not-An-Annotation"}
+ value = [payload] if instance_keyword in ("enum", "examples") else payload
+ assert collect_header_params(
+ {
+ "type": "object",
+ "properties": {
+ "schema_arg": {"type": "object", instance_keyword: value},
+ "region": {"type": "string", "x-mcp-header": "X-Region"},
+ },
+ }
+ ) == [HeaderParam(path=("region",), header_name="X-Region", json_type="string")]
+
+ def test_annotation_behind_composition_is_still_rejected(self):
+ """Skipping instance data must not weaken the reachability guard."""
+ with pytest.raises(InvalidHeaderAnnotation):
+ collect_header_params(
+ {
+ "properties": {
+ "a": {
+ "type": "object",
+ "default": {"x-mcp-header": "X-Payload"},
+ "anyOf": [{"type": "string", "x-mcp-header": "X-Hidden"}],
+ }
+ }
+ }
+ )
+
+
+# ───────────────────────── era cache ─────────────────────────
+
+
+class TestEraCache:
+ def test_set_get_forget(self):
+ cache = MCPServerEraCache(ttl_seconds=60)
+ value = MCPServerProtocol(
+ era=MCPProtocolEra.MODERN, protocol_version=MODERN_PROTOCOL_VERSION
+ )
+ assert cache.get(SERVER_URL) is None
+ cache.set(SERVER_URL, value)
+ assert cache.get(SERVER_URL) == value
+ cache.forget(SERVER_URL)
+ assert cache.get(SERVER_URL) is None
+
+ def test_entries_expire(self):
+ cache = MCPServerEraCache(ttl_seconds=0)
+ cache.set(
+ SERVER_URL,
+ MCPServerProtocol(
+ era=MCPProtocolEra.LEGACY, protocol_version=LEGACY_PROTOCOL_VERSION
+ ),
+ )
+ assert cache.get(SERVER_URL) is None
+
+ def test_least_recently_used_entry_is_evicted(self):
+ cache = MCPServerEraCache(ttl_seconds=60, max_entries=2)
+ legacy = MCPServerProtocol(
+ era=MCPProtocolEra.LEGACY, protocol_version=LEGACY_PROTOCOL_VERSION
+ )
+ cache.set("https://a.example/mcp", legacy)
+ cache.set("https://b.example/mcp", legacy)
+ # Touching ``a`` makes ``b`` the oldest entry.
+ assert cache.get("https://a.example/mcp") is legacy
+ cache.set("https://c.example/mcp", legacy)
+ assert len(cache) == 2
+ assert cache.get("https://b.example/mcp") is None
+ assert cache.get("https://a.example/mcp") is legacy
+ assert cache.get("https://c.example/mcp") is legacy
+
+
+# ───────────────────────── fake transport ─────────────────────────
+
+
+class _FakeResponse(Response):
+ """A canned ``Response``; decoding and status handling are inherited."""
+
+ def __init__( # pyright: ignore[reportMissingSuperCall]
+ self,
+ status: int,
+ body: Any = None,
+ *,
+ headers: dict[str, str] | None = None,
+ text: str | None = None,
+ ):
+ self.status = status
+ self.reason = "reason"
+ self.headers = {"content-type": "application/json"} # type: ignore[assignment]
+ self.headers.update(headers or {})
+ self.url = SERVER_URL
+ if text is not None:
+ self.content = text.encode()
+ elif body is None:
+ self.content = b""
+ else:
+ self.content = json.dumps(body).encode()
+
+
+def _rpc_result(result: Any, request_id: int = 1) -> dict[str, Any]:
+ return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+
+def _rpc_error(code: int, message: str = "err", data: Any = None) -> dict[str, Any]:
+ error: dict[str, Any] = {"code": code, "message": message}
+ if data is not None:
+ error["data"] = data
+ return {"jsonrpc": "2.0", "id": 1, "error": error}
+
+
+DISCOVER_RESULT = {
+ "resultType": "complete",
+ "supportedVersions": [MODERN_PROTOCOL_VERSION],
+ "capabilities": {"tools": {}},
+ "_meta": {META_SERVER_INFO: {"name": "modern", "version": "1"}},
+}
+
+LEGACY_INIT_RESULT = {
+ "protocolVersion": LEGACY_PROTOCOL_VERSION,
+ "capabilities": {"tools": {}},
+ "serverInfo": {"name": "legacy", "version": "1"},
+}
+
+
+class _Transport:
+ """Scripted replies keyed by JSON-RPC method, recording every request."""
+
+ def __init__(self, script: dict[str, list[_FakeResponse]]):
+ self.script = {k: list(v) for k, v in script.items()}
+ self.sent: list[tuple[dict[str, Any], dict[str, str]]] = []
+
+ def __call__(self, payload: dict[str, Any], headers: dict[str, str]):
+ self.sent.append((payload, headers))
+ queue = self.script.get(payload["method"])
+ if not queue:
+ raise AssertionError(f"unexpected request {payload['method']}")
+ # Replies are consumed in order; the last one is sticky and answers
+ # every further request, so a one-entry script is "always reply X".
+ return queue.pop(0) if len(queue) > 1 else queue[0]
+
+ def methods(self) -> list[str]:
+ return [p["method"] for p, _ in self.sent]
+
+
+def _client(transport: _Transport, **kwargs) -> MCPClient:
+ client = MCPClient(SERVER_URL, **kwargs)
+ patch.object(client, "_post", side_effect=transport).start()
+ patch.object(client, "_send_notification").start()
+ return client
+
+
[email protected](autouse=True)
+def _stop_patches():
+ yield
+ patch.stopall()
+
+
+# ───────────────────────── era detection ─────────────────────────
+
+
+class TestEraDetection:
+ async def test_modern_server_detected_via_discover(self):
+ transport = _Transport(
+ {"server/discover": [_FakeResponse(200, _rpc_result(DISCOVER_RESULT))]}
+ )
+ client = _client(transport)
+ result = await client.initialize()
+
+ assert client.era is MCPProtocolEra.MODERN
+ assert client.protocol_version == MODERN_PROTOCOL_VERSION
+ assert result["protocolVersion"] == MODERN_PROTOCOL_VERSION
+ assert result["serverInfo"] == {"name": "modern", "version": "1"}
+ assert transport.methods() == ["server/discover"]
+
+ payload, headers = transport.sent[0]
+ meta = payload["params"]["_meta"]
+ assert meta[META_PROTOCOL_VERSION] == MODERN_PROTOCOL_VERSION
+ assert headers[HEADER_PROTOCOL_VERSION] == MODERN_PROTOCOL_VERSION
+ assert headers[HEADER_METHOD] == "server/discover"
+ assert HEADER_NAME not in headers
+ assert HEADER_SESSION_ID not in headers
+ cached = era_cache.get(SERVER_URL)
+ assert cached == MCPServerProtocol(
+ era=MCPProtocolEra.MODERN, protocol_version=MODERN_PROTOCOL_VERSION
+ )
+
+ async def test_legacy_server_answering_method_not_found(self):
+ """Legacy servers reply 200 + -32601 to an unknown method."""
+ transport = _Transport(
+ {
+ "server/discover": [
+ _FakeResponse(200, _rpc_error(ERROR_METHOD_NOT_FOUND))
+ ],
+ "initialize": [_FakeResponse(200, _rpc_result(LEGACY_INIT_RESULT))],
+ }
+ )
+ client = _client(transport)
+ result = await client.initialize()
+
+ assert client.era is MCPProtocolEra.LEGACY
+ assert result == LEGACY_INIT_RESULT
+ assert transport.methods() == ["server/discover", "initialize"]
+ init_payload, init_headers = transport.sent[1]
+ assert init_payload["params"]["protocolVersion"] == LEGACY_PROTOCOL_VERSION
+ assert "_meta" not in init_payload["params"]
+ assert HEADER_PROTOCOL_VERSION not in init_headers
+ assert HEADER_METHOD not in init_headers
+
+ async def test_legacy_server_answering_plain_400(self):
+ """Reference legacy SDKs answer 400 'Missing session ID' with no JSON."""
+ transport = _Transport(
+ {
+ "server/discover": [
+ _FakeResponse(
+ 400,
+ text="Bad Request: Missing session ID",
+ headers={"content-type": "text/plain"},
+ )
+ ],
+ "initialize": [_FakeResponse(200, _rpc_result(LEGACY_INIT_RESULT))],
+ }
+ )
+ client = _client(transport)
+ await client.initialize()
+ assert client.era is MCPProtocolEra.LEGACY
+ assert era_cache.get(SERVER_URL) == MCPServerProtocol(
+ era=MCPProtocolEra.LEGACY, protocol_version=LEGACY_PROTOCOL_VERSION
+ )
+
+ @pytest.mark.parametrize("status", [404, 405, 406, 415])
+ async def test_legacy_server_other_4xx_without_modern_body(self, status: int):
+ transport = _Transport(
+ {
+ "server/discover": [_FakeResponse(status)],
+ "initialize": [_FakeResponse(200, _rpc_result(LEGACY_INIT_RESULT))],
+ }
+ )
+ client = _client(transport)
+ await client.initialize()
+ assert client.era is MCPProtocolEra.LEGACY
+
+ async def test_modern_400_with_modern_error_is_not_a_fallback(self):
+ """A 400 carrying a spec-reserved error code proves a modern server."""
+ transport = _Transport(
+ {
+ "server/discover": [
+ _FakeResponse(400, _rpc_error(ERROR_HEADER_MISMATCH, "mismatch"))
+ ],
+ }
+ )
+ client = _client(transport)
+ with pytest.raises(MCPClientError, match=r"\[-32020\]"):
+ await client.initialize()
+ assert transport.methods() == ["server/discover"]
+ assert client.era is None
+
+ async def test_version_negotiation_on_probe(self):
+ rejected = _FakeResponse(
+ 400,
+ _rpc_error(
+ ERROR_UNSUPPORTED_PROTOCOL_VERSION,
+ data={"supported": ["2099-01-01", MODERN_PROTOCOL_VERSION]},
+ ),
+ )
+ accepted = _FakeResponse(200, _rpc_result(DISCOVER_RESULT))
+ transport = _Transport({"server/discover": [rejected, accepted]})
+ client = _client(transport)
+ await client.initialize()
+
+ assert client.era is MCPProtocolEra.MODERN
+ assert transport.methods() == ["server/discover", "server/discover"]
+ _, second_headers = transport.sent[1]
+ assert second_headers[HEADER_PROTOCOL_VERSION] == MODERN_PROTOCOL_VERSION
+
+ async def test_no_mutual_version_raises(self):
+ transport = _Transport(
+ {
+ "server/discover": [
+ _FakeResponse(
+ 400,
+ _rpc_error(
+ ERROR_UNSUPPORTED_PROTOCOL_VERSION,
+ data={"supported": ["2099-01-01"]},
+ ),
+ )
+ ]
+ }
+ )
+ client = _client(transport)
+ with pytest.raises(MCPClientError, match="does not support any protocol"):
+ await client.initialize()
+
+ @pytest.mark.parametrize("status", [401, 403, 407, 429])
+ async def test_auth_failures_propagate_without_fallback(self, status: int):
+ transport = _Transport({"server/discover": [_FakeResponse(status)]})
+ client = _client(transport, authorization="Bearer bad")
+ with pytest.raises(HTTPClientError) as exc:
+ await client.initialize()
+ assert exc.value.status_code == status
+ assert transport.methods() == ["server/discover"]
+ assert era_cache.get(SERVER_URL) is None
+
+ async def test_server_error_propagates(self):
+ transport = _Transport({"server/discover": [_FakeResponse(503)]})
+ client = _client(transport)
+ with pytest.raises(HTTPServerError):
+ await client.initialize()
+
+ async def test_discover_result_without_versions_is_still_modern(self):
+ """Only a modern server answers server/discover with a *result*."""
+ transport = _Transport(
+ {
+ "server/discover": [
+ _FakeResponse(
+ 200,
+ _rpc_result(
+ {
+ "capabilities": {"tools": {}},
+ "_meta": {META_SERVER_INFO: {"name": "m"}},
+ }
+ ),
+ )
+ ]
+ }
+ )
+ client = _client(transport)
+ result = await client.initialize()
+ assert client.era is MCPProtocolEra.MODERN
+ assert client.protocol_version == MODERN_PROTOCOL_VERSION
+ assert result["serverInfo"] == {"name": "m"}
+ assert transport.methods() == ["server/discover"]
+
+ async def test_cached_legacy_skips_modern_probe(self):
+ era_cache.set(
+ SERVER_URL,
+ MCPServerProtocol(
+ era=MCPProtocolEra.LEGACY, protocol_version=LEGACY_PROTOCOL_VERSION
+ ),
+ )
+ transport = _Transport(
+ {"initialize": [_FakeResponse(200, _rpc_result(LEGACY_INIT_RESULT))]}
+ )
+ client = _client(transport)
+ await client.initialize()
+ assert transport.methods() == ["initialize"]
+
+ async def test_cached_legacy_reprobes_when_handshake_rejected(self):
+ """A server that upgraded to modern-only rejects initialize; re-detect."""
+ era_cache.set(
+ SERVER_URL,
+ MCPServerProtocol(
+ era=MCPProtocolEra.LEGACY, protocol_version=LEGACY_PROTOCOL_VERSION
+ ),
+ )
+ transport = _Transport(
+ {
+ "initialize": [_FakeResponse(404, _rpc_error(ERROR_METHOD_NOT_FOUND))],
+ "server/discover": [_FakeResponse(200, _rpc_result(DISCOVER_RESULT))],
+ }
+ )
+ client = _client(transport)
+ await client.initialize()
+ assert client.era is MCPProtocolEra.MODERN
+ assert transport.methods() == ["initialize", "server/discover"]
+
+ async def test_cached_modern_reprobes_when_discover_fails(self):
+ era_cache.set(
+ SERVER_URL,
+ MCPServerProtocol(
+ era=MCPProtocolEra.MODERN, protocol_version=MODERN_PROTOCOL_VERSION
+ ),
+ )
+ transport = _Transport(
+ {
+ "server/discover": [
+ _FakeResponse(200, _rpc_error(ERROR_METHOD_NOT_FOUND)),
+ _FakeResponse(200, _rpc_error(ERROR_METHOD_NOT_FOUND)),
+ ],
+ "initialize": [_FakeResponse(200, _rpc_result(LEGACY_INIT_RESULT))],
+ }
+ )
+ client = _client(transport)
+ await client.initialize()
+ assert client.era is MCPProtocolEra.LEGACY
+
+ async def test_cached_modern_reprobes_after_plain_400(self):
+ """A rolled-back server answers server/discover with a bare 400."""
+ era_cache.set(
+ SERVER_URL,
+ MCPServerProtocol(
+ era=MCPProtocolEra.MODERN, protocol_version=MODERN_PROTOCOL_VERSION
+ ),
+ )
+ transport = _Transport(
+ {
+ "server/discover": [
+ _FakeResponse(400, text="Bad Request: Missing session ID"),
+ _FakeResponse(400, text="Bad Request: Missing session ID"),
+ ],
+ "initialize": [_FakeResponse(200, _rpc_result(LEGACY_INIT_RESULT))],
+ }
+ )
+ client = _client(transport)
+ await client.initialize()
+ assert client.era is MCPProtocolEra.LEGACY
+ cached = era_cache.get(SERVER_URL)
+ assert cached is not None and cached.era is MCPProtocolEra.LEGACY
+ assert transport.methods() == [
+ "server/discover",
+ "server/discover",
+ "initialize",
+ ]
+
+ @pytest.mark.parametrize("status", [401, 403, 407, 429])
+ async def test_cached_modern_keeps_cache_on_credential_errors(self, status):
+ cached = MCPServerProtocol(
+ era=MCPProtocolEra.MODERN, protocol_version=MODERN_PROTOCOL_VERSION
+ )
+ era_cache.set(SERVER_URL, cached)
+ transport = _Transport({"server/discover": [_FakeResponse(status)]})
+ client = _client(transport, authorization="Bearer stale")
+ with pytest.raises(HTTPClientError) as exc:
+ await client.initialize()
+ assert exc.value.status_code == status
+ assert transport.methods() == ["server/discover"]
+ assert era_cache.get(SERVER_URL) == cached
+
+ async def test_cached_legacy_reprobes_after_jsonrpc_error(self):
+ """A 200 carrying a JSON-RPC error on initialize also re-detects."""
+ era_cache.set(
+ SERVER_URL,
+ MCPServerProtocol(
+ era=MCPProtocolEra.LEGACY, protocol_version=LEGACY_PROTOCOL_VERSION
+ ),
+ )
+ transport = _Transport(
+ {
+ "initialize": [_FakeResponse(200, _rpc_error(ERROR_METHOD_NOT_FOUND))],
+ "server/discover": [_FakeResponse(200, _rpc_result(DISCOVER_RESULT))],
+ }
+ )
+ client = _client(transport)
+ await client.initialize()
+ assert client.era is MCPProtocolEra.MODERN
+ assert transport.methods() == ["initialize", "server/discover"]
+
+ @pytest.mark.parametrize("status", [401, 403, 407, 429])
+ async def test_cached_legacy_keeps_cache_on_credential_errors(self, status):
+ cached = MCPServerProtocol(
+ era=MCPProtocolEra.LEGACY, protocol_version=LEGACY_PROTOCOL_VERSION
+ )
+ era_cache.set(SERVER_URL, cached)
+ transport = _Transport({"initialize": [_FakeResponse(status)]})
+ client = _client(transport, authorization="Bearer stale")
+ with pytest.raises(HTTPClientError) as exc:
+ await client.initialize()
+ assert exc.value.status_code == status
+ assert transport.methods() == ["initialize"]
+ assert era_cache.get(SERVER_URL) == cached
+
+ async def test_send_request_detects_era_lazily(self):
+ transport = _Transport(
+ {
+ "server/discover": [_FakeResponse(200, _rpc_result(DISCOVER_RESULT))],
+ "tools/list": [
+ _FakeResponse(200, _rpc_result({"tools": [], "ttlMs": 1}))
+ ],
+ }
+ )
+ client = _client(transport)
+ tools = await client.list_tools()
+ assert tools == []
+ assert transport.methods() == ["server/discover", "tools/list"]
+
+
+class TestSloppyServerPayloads:
+ """A single out-of-spec field must not take down a whole server."""
+
+ async def test_null_tool_description_is_tolerated(self):
+ """``"description": null`` must not fail model validation.
+
+ The key is present, so ``.get(..., "")`` returns ``None``; without a
+ fallback that raises ``ValidationError``, which the discovery route
+ does not catch and answers 502 for every tool on the server.
+ """
+ transport = _Transport(
+ {
+ "server/discover": [_FakeResponse(200, _rpc_result(DISCOVER_RESULT))],
+ "tools/list": [
+ _FakeResponse(
+ 200,
+ _rpc_result(
+ {
+ "tools": [
+ {
+ "name": "quiet",
+ "description": None,
+ "inputSchema": {"type": "object"},
+ }
+ ]
+ }
+ ),
+ )
+ ],
+ }
+ )
+ tools = await _client(transport).list_tools()
+ assert [(t.name, t.description) for t in tools] == [("quiet", "")]
+
+ async def test_non_object_content_items_become_text_blocks(self):
+ transport = _Transport(
+ {
+ "server/discover": [_FakeResponse(200, _rpc_result(DISCOVER_RESULT))],
+ "tools/call": [
+ _FakeResponse(
+ 200, _rpc_result({"content": ["plain", {"type": "text"}]})
+ )
+ ],
+ }
+ )
+ result = await _client(transport).call_tool("echo", {})
+ assert result.content == [{"type": "text", "text": "plain"}, {"type": "text"}]
+ assert result.is_error is False
+
+
+class TestHttpRetries:
+ """Retries are bounded, and never applied to tool execution."""
+
+ @pytest.mark.parametrize(
+ ("method", "attempts"),
+ [("tools/call", 1), ("tools/list", 3), ("server/discover", 3)],
+ )
+ async def test_retry_budget_per_method(self, method: str, attempts: int):
+ client = MCPClient(SERVER_URL)
+ with patch("backend.blocks.mcp.client.Requests") as MockRequests:
+ MockRequests.return_value.post = AsyncMock(
+ return_value=_FakeResponse(200, _rpc_result({}))
+ )
+ await client._post({"jsonrpc": "2.0", "id": 1, "method": method}, {})
+ assert MockRequests.call_args.kwargs["retry_max_attempts"] == attempts
+
+
+# ───────────────────────── legacy requests ─────────────────────────
+
+
+class TestLegacyRequests:
+ async def test_session_id_is_captured_echoed_and_released(self):
+ transport = _Transport(
+ {
+ "server/discover": [
+ _FakeResponse(200, _rpc_error(ERROR_METHOD_NOT_FOUND))
+ ],
+ "initialize": [
+ _FakeResponse(
+ 200,
+ _rpc_result(LEGACY_INIT_RESULT),
+ headers={HEADER_SESSION_ID: "sess-1"},
+ )
+ ],
+ "tools/list": [_FakeResponse(200, _rpc_result({"tools": []}))],
+ }
+ )
+ client = _client(transport)
+ await client.initialize()
+ await client.list_tools()
+
+ _, list_headers = transport.sent[-1]
+ assert list_headers[HEADER_SESSION_ID] == "sess-1"
+ assert HEADER_PROTOCOL_VERSION not in list_headers
+
+ deleted: list[dict[str, str]] = []
+
+ class _FakeRequests:
+ def __init__(self, *a, **kw):
+ deleted.append(kw.get("extra_headers") or {})
+
+ async def delete(self, url):
+ return _FakeResponse(200)
+
+ with patch("backend.blocks.mcp.client.Requests", _FakeRequests):
+ await client.close()
+ assert deleted[0][HEADER_SESSION_ID] == "sess-1"
+ assert client._session_id is None
+
+ async def test_legacy_jsonrpc_error_raises(self):
+ transport = _Transport(
+ {
+ "server/discover": [
+ _FakeResponse(200, _rpc_error(ERROR_METHOD_NOT_FOUND))
+ ],
+ "initialize": [_FakeResponse(200, _rpc_result(LEGACY_INIT_RESULT))],
+ "tools/call": [_FakeResponse(200, _rpc_error(-32602, "Unknown tool"))],
+ }
+ )
+ client = _client(transport)
+ await client.initialize()
+ with pytest.raises(MCPClientError, match=r"\[-32602\]: Unknown tool"):
+ await client.call_tool("nope", {})
+
+ async def test_legacy_http_error_raises_client_error(self):
+ transport = _Transport(
+ {
+ "server/discover": [
+ _FakeResponse(200, _rpc_error(ERROR_METHOD_NOT_FOUND))
+ ],
+ "initialize": [_FakeResponse(200, _rpc_result(LEGACY_INIT_RESULT))],
+ "tools/list": [_FakeResponse(403, text="nope")],
+ }
+ )
+ client = _client(transport)
+ await client.initialize()
+ with pytest.raises(HTTPClientError) as exc:
+ await client.list_tools()
+ assert exc.value.status_code == 403
+ assert "Body: nope" in str(exc.value)
+
+
+# ───────────────────────── modern requests ─────────────────────────
+
+
+def _modern_client(
+ extra: dict[str, list[_FakeResponse]]
+) -> tuple[MCPClient, _Transport]:
+ script = {"server/discover": [_FakeResponse(200, _rpc_result(DISCOVER_RESULT))]}
+ script.update(extra)
+ transport = _Transport(script)
+ return _client(transport), transport
+
+
+class TestModernRequests:
+ async def test_tools_call_headers_and_meta(self):
+ client, transport = _modern_client(
+ {
+ "tools/call": [
+ _FakeResponse(
+ 200,
+ _rpc_result(
+ {
+ "resultType": "complete",
+ "content": [{"type": "text", "text": "ok"}],
+ }
+ ),
+ )
+ ]
+ }
+ )
+ await client.initialize()
+ result = await client.call_tool("get_weather", {"city": "Oslo"})
+
+ assert result.content == [{"type": "text", "text": "ok"}]
+ payload, headers = transport.sent[-1]
+ assert headers[HEADER_METHOD] == "tools/call"
+ assert headers[HEADER_NAME] == "get_weather"
+ assert headers[HEADER_PROTOCOL_VERSION] == MODERN_PROTOCOL_VERSION
+ assert payload["params"]["name"] == "get_weather"
+ assert payload["params"]["arguments"] == {"city": "Oslo"}
+ assert payload["params"]["_meta"][META_PROTOCOL_VERSION] == (
+ MODERN_PROTOCOL_VERSION
+ )
+
+ async def test_tool_name_needing_encoding(self):
+ client, transport = _modern_client(
+ {"tools/call": [_FakeResponse(200, _rpc_result({"content": []}))]}
+ )
+ await client.initialize()
+ await client.call_tool("näme with space", {})
+ _, headers = transport.sent[-1]
+ assert headers[HEADER_NAME].startswith("=?base64?")
+ assert decode_header_value(headers[HEADER_NAME]) == "näme with space"
+
+ async def test_absent_result_type_is_complete(self):
+ client, _ = _modern_client(
+ {"tools/call": [_FakeResponse(200, _rpc_result({"content": []}))]}
+ )
+ await client.initialize()
+ result = await client.call_tool("t", {})
+ assert not result.is_error
+
+ async def test_unknown_result_type_rejected(self):
+ client, _ = _modern_client(
+ {
+ "tools/call": [
+ _FakeResponse(200, _rpc_result({"resultType": "something_new"}))
+ ]
+ }
+ )
+ await client.initialize()
+ with pytest.raises(MCPClientError, match="unrecognized resultType"):
+ await client.call_tool("t", {})
+
+ async def test_x_mcp_header_params_mirrored_from_list_tools(self):
+ tool = {
+ "name": "execute_sql",
+ "description": "",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "region": {"type": "string", "x-mcp-header": "Region"},
+ "query": {"type": "string"},
+ },
+ },
+ }
+ client, transport = _modern_client(
+ {
+ "tools/list": [_FakeResponse(200, _rpc_result({"tools": [tool]}))],
+ "tools/call": [_FakeResponse(200, _rpc_result({"content": []}))],
+ }
+ )
+ await client.initialize()
+ tools = await client.list_tools()
+ assert [t.name for t in tools] == ["execute_sql"]
+ await client.call_tool("execute_sql", {"region": "us-west1", "query": "x"})
+ _, headers = transport.sent[-1]
+ assert headers["Mcp-Param-Region"] == "us-west1"
+
+ async def test_x_mcp_header_params_from_caller_supplied_schema(self):
+ client, transport = _modern_client(
+ {"tools/call": [_FakeResponse(200, _rpc_result({"content": []}))]}
+ )
+ await client.initialize()
+ schema = {
+ "type": "object",
+ "properties": {"region": {"type": "string", "x-mcp-header": "Region"}},
+ }
+ await client.call_tool("execute_sql", {"region": "eu"}, input_schema=schema)
+ _, headers = transport.sent[-1]
+ assert headers["Mcp-Param-Region"] == "eu"
+
+ async def test_header_mismatch_refreshes_schema_and_retries(self):
+ tool = {
+ "name": "execute_sql",
+ "inputSchema": {
+ "type": "object",
+ "properties": {"region": {"type": "string", "x-mcp-header": "Region"}},
+ },
+ }
+ client, transport = _modern_client(
+ {
+ "tools/call": [
+ _FakeResponse(400, _rpc_error(ERROR_HEADER_MISMATCH)),
+ _FakeResponse(200, _rpc_result({"content": []})),
+ ],
+ "tools/list": [_FakeResponse(200, _rpc_result({"tools": [tool]}))],
+ }
+ )
+ await client.initialize()
+ await client.call_tool("execute_sql", {"region": "eu"})
+ assert transport.methods() == [
+ "server/discover",
+ "tools/call",
+ "tools/list",
+ "tools/call",
+ ]
+ _, retry_headers = transport.sent[-1]
+ assert retry_headers["Mcp-Param-Region"] == "eu"
+ first_id = transport.sent[1][0]["id"]
+ assert transport.sent[-1][0]["id"] != first_id
+
+ async def test_invalid_header_annotation_drops_tool(self):
+ tools = [
+ {"name": "good", "inputSchema": {"type": "object"}},
+ {
+ "name": "bad",
+ "inputSchema": {
+ "type": "object",
+ "properties": {"n": {"type": "number", "x-mcp-header": "N"}},
+ },
+ },
+ ]
+ client, _ = _modern_client(
+ {"tools/list": [_FakeResponse(200, _rpc_result({"tools": tools}))]}
+ )
+ await client.initialize()
+ listed = await client.list_tools()
+ assert [t.name for t in listed] == ["good"]
+
+ async def test_input_required_with_request_state_is_retried(self):
+ client, transport = _modern_client(
+ {
+ "tools/call": [
+ _FakeResponse(
+ 200,
+ _rpc_result(
+ {"resultType": "input_required", "requestState": "s1"}
+ ),
+ ),
+ _FakeResponse(
+ 200,
+ _rpc_result({"content": [{"type": "text", "text": "done"}]}),
+ ),
+ ]
+ }
+ )
+ await client.initialize()
+ result = await client.call_tool("confirm", {"a": 1})
+ assert result.content[0]["text"] == "done"
+ retry_payload, _ = transport.sent[-1]
+ assert retry_payload["params"]["requestState"] == "s1"
+ assert retry_payload["params"]["arguments"] == {"a": 1}
+ assert "inputResponses" not in retry_payload["params"]
+
+ async def test_input_required_with_input_requests_is_an_error(self):
+ client, _ = _modern_client(
+ {
+ "tools/call": [
+ _FakeResponse(
+ 200,
+ _rpc_result(
+ {
+ "resultType": "input_required",
+ "inputRequests": {
+ "q": {"method": "elicitation/create", "params": {}}
+ },
+ }
+ ),
+ )
+ ]
+ }
+ )
+ await client.initialize()
+ with pytest.raises(MCPClientError, match="requires interactive input"):
+ await client.call_tool("ask", {})
+
+ async def test_input_required_loop_is_bounded(self):
+ # One sticky reply: the server asks for another round-trip forever.
+ client, transport = _modern_client(
+ {
+ "tools/call": [
+ _FakeResponse(
+ 200,
+ _rpc_result(
+ {"resultType": "input_required", "requestState": "again"}
+ ),
+ )
+ ]
+ }
+ )
+ await client.initialize()
+ with pytest.raises(MCPClientError, match="kept requesting more input"):
+ await client.call_tool("loop", {})
+ assert transport.methods().count("tools/call") == 4
+
+ async def test_input_required_completes_on_last_permitted_round_trip(self):
+ """The reply to the final retry is inspected, not discarded."""
+ interim = _FakeResponse(
+ 200,
+ _rpc_result({"resultType": "input_required", "requestState": "again"}),
+ )
+ final = _FakeResponse(
+ 200, _rpc_result({"content": [{"type": "text", "text": "DONE"}]})
+ )
+ client, transport = _modern_client({"tools/call": [interim] * 3 + [final]})
+ await client.initialize()
+ result = await client.call_tool("slow", {})
+ assert not result.is_error
+ assert result.content == [{"type": "text", "text": "DONE"}]
+ assert transport.methods().count("tools/call") == 4
+
+ async def test_call_tool_rejects_invalid_annotation_in_known_schema(self):
+ client, transport = _modern_client(
+ {"tools/call": [_FakeResponse(200, _rpc_result({"content": []}))]}
+ )
+ await client.initialize()
+ schema = {
+ "type": "object",
+ "properties": {"tags": {"type": "array", "x-mcp-header": "Tags"}},
+ }
+ with pytest.raises(MCPClientError, match="invalid x-mcp-header"):
+ await client.call_tool("tagged", {"tags": []}, input_schema=schema)
+ assert "tools/call" not in transport.methods()
+
+ async def test_alternating_version_and_header_errors_terminate(self):
+ """Each retry kind happens at most once, whatever order they arrive in."""
+ client, transport = _modern_client(
+ {
+ "tools/list": [_FakeResponse(200, _rpc_result({"tools": []}))],
+ "tools/call": [
+ _FakeResponse(400, _rpc_error(ERROR_HEADER_MISMATCH)),
+ _FakeResponse(
+ 400,
+ _rpc_error(
+ ERROR_UNSUPPORTED_PROTOCOL_VERSION,
+ data={"supported": [MODERN_PROTOCOL_VERSION]},
+ ),
+ ),
+ _FakeResponse(400, _rpc_error(ERROR_HEADER_MISMATCH)),
+ ],
+ }
+ )
+ await client.initialize()
+ with pytest.raises(MCPClientError, match=str(ERROR_HEADER_MISMATCH)):
+ await client.call_tool("t", {})
+ assert transport.methods().count("tools/call") == 3
+ assert transport.methods().count("tools/list") == 1
+
+ @pytest.mark.parametrize("status", [401, 403, 407, 429])
+ async def test_credential_errors_with_envelope_keep_http_meaning(self, status):
+ """A JSON-RPC envelope on a 401 must not turn it into MCPClientError."""
+ client, _ = _modern_client(
+ {"tools/call": [_FakeResponse(status, _rpc_error(-32001, "Unauthorized"))]}
+ )
+ await client.initialize()
+ with pytest.raises(HTTPClientError) as exc:
+ await client.call_tool("t", {})
+ assert exc.value.status_code == status
+
+ async def test_server_error_with_envelope_keeps_http_meaning(self):
+ client, _ = _modern_client(
+ {"tools/call": [_FakeResponse(503, _rpc_error(-32000, "down"))]}
+ )
+ await client.initialize()
+ with pytest.raises(HTTPServerError):
+ await client.call_tool("t", {})
+
+ async def test_cached_modern_401_with_envelope_keeps_cache(self):
+ cached = MCPServerProtocol(
+ era=MCPProtocolEra.MODERN, protocol_version=MODERN_PROTOCOL_VERSION
+ )
+ era_cache.set(SERVER_URL, cached)
+ transport = _Transport(
+ {"server/discover": [_FakeResponse(401, _rpc_error(-32001, "expired"))]}
+ )
+ client = _client(transport, authorization="Bearer expired")
+ with pytest.raises(HTTPClientError) as exc:
+ await client.initialize()
+ assert exc.value.status_code == 401
+ assert era_cache.get(SERVER_URL) == cached
+
+ async def test_missing_capability_error(self):
+ client, _ = _modern_client(
+ {
+ "tools/call": [
+ _FakeResponse(
+ 400,
+ _rpc_error(
+ ERROR_MISSING_CLIENT_CAPABILITY,
+ data={"requiredCapabilities": ["elicitation"]},
+ ),
+ )
+ ]
+ }
+ )
+ await client.initialize()
+ with pytest.raises(MCPClientError, match="requires client capabilities"):
+ await client.call_tool("t", {})
+
+ async def test_method_not_found_404(self):
+ client, _ = _modern_client(
+ {"tools/list": [_FakeResponse(404, _rpc_error(ERROR_METHOD_NOT_FOUND))]}
+ )
+ await client.initialize()
+ with pytest.raises(MCPClientError, match="does not support tools/list"):
+ await client.list_tools()
+
+ async def test_version_renegotiated_mid_session(self):
+ client, transport = _modern_client(
+ {
+ "tools/list": [
+ _FakeResponse(
+ 400,
+ _rpc_error(
+ ERROR_UNSUPPORTED_PROTOCOL_VERSION,
+ data={"supported": [MODERN_PROTOCOL_VERSION]},
+ ),
+ ),
+ _FakeResponse(200, _rpc_result({"tools": []})),
+ ]
+ }
+ )
+ await client.initialize()
+ assert await client.list_tools() == []
+ assert transport.methods() == ["server/discover", "tools/list", "tools/list"]
+
+ async def test_sse_reply_is_parsed(self):
+ sse = (
+ "event: message\n"
+ f"data: {json.dumps(_rpc_result({'tools': [], 'resultType': 'complete'}))}\n\n"
+ )
+ client, _ = _modern_client(
+ {
+ "tools/list": [
+ _FakeResponse(
+ 200, text=sse, headers={"content-type": "text/event-stream"}
+ )
+ ]
+ }
+ )
+ await client.initialize()
+ assert await client.list_tools() == []
+
+ async def test_auth_error_propagates(self):
+ client, _ = _modern_client({"tools/list": [_FakeResponse(401)]})
+ await client.initialize()
+ with pytest.raises(HTTPClientError) as exc:
+ await client.list_tools()
+ assert exc.value.status_code == 401
+
+ async def test_close_is_noop_for_stateless_server(self):
+ client, _ = _modern_client({})
+ await client.initialize()
+ with patch("backend.blocks.mcp.client.Requests") as requests_cls:
+ await client.close()
+ requests_cls.assert_not_called()
diff --git a/autogpt_platform/backend/backend/blocks/mcp/test_server.py b/autogpt_platform/backend/backend/blocks/mcp/test_server.py
index a6732932bc..9535125bee 100644
--- a/autogpt_platform/backend/backend/blocks/mcp/test_server.py
+++ b/autogpt_platform/backend/backend/blocks/mcp/test_server.py
@@ -3,15 +3,47 @@ Minimal MCP server for integration testing.
Implements the MCP Streamable HTTP transport (JSON-RPC 2.0 over HTTP POST)
with a few sample tools. Runs on localhost with a random available port.
+
+The server can speak either protocol era so the client's dual-era behaviour
+is exercised against real HTTP:
+
+* ``era="legacy"`` — ``initialize`` handshake (``2025-03-26``), optional
+ ``Mcp-Session-Id`` sessions, JSON-RPC ``-32601`` for unknown methods.
+* ``era="modern"`` — stateless ``2026-07-28``: validates ``_meta`` and the
+ mirrored ``Mcp-*`` headers, implements ``server/discover``, returns
+ ``resultType`` / ``ttlMs`` / ``cacheScope``, and rejects ``initialize``.
+* ``era="dual"`` — serves whichever era the client opens with.
"""
import json
import logging
+import uuid
+from typing import Literal
from aiohttp import web
+from backend.blocks.mcp.protocol import (
+ ERROR_HEADER_MISMATCH,
+ ERROR_INVALID_PARAMS,
+ ERROR_METHOD_NOT_FOUND,
+ ERROR_UNSUPPORTED_PROTOCOL_VERSION,
+ HEADER_METHOD,
+ HEADER_NAME,
+ HEADER_PARAM_PREFIX,
+ HEADER_PROTOCOL_VERSION,
+ HEADER_SESSION_ID,
+ LEGACY_PROTOCOL_VERSION,
+ META_CLIENT_CAPABILITIES,
+ META_PROTOCOL_VERSION,
+ META_SERVER_INFO,
+ MODERN_PROTOCOL_VERSION,
+ decode_header_value,
+)
+
logger = logging.getLogger(__name__)
+SERVER_INFO = {"name": "test-mcp-server", "version": "1.0.0"}
+
# Sample tools this test server exposes
TEST_TOOLS = [
{
@@ -53,20 +85,50 @@ TEST_TOOLS = [
},
]
+# Extra tools only a modern (2026-07-28) server exposes.
+MODERN_EXTRA_TOOLS = [
+ {
+ # ``region`` must be mirrored into ``Mcp-Param-Region``.
+ "name": "execute_sql",
+ "description": "Run SQL in a region",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "region": {"type": "string", "x-mcp-header": "Region"},
+ "query": {"type": "string"},
+ },
+ "required": ["region", "query"],
+ },
+ },
+ {
+ # First call answers ``input_required`` with only ``requestState``.
+ "name": "needs_confirmation",
+ "description": "Completes on the second round-trip",
+ "inputSchema": {"type": "object", "properties": {}},
+ },
+ {
+ # Asks for elicitation, which this client does not support.
+ "name": "needs_elicitation",
+ "description": "Requests interactive input",
+ "inputSchema": {"type": "object", "properties": {}},
+ },
+ {
+ # ``x-mcp-header`` on a ``number`` parameter is invalid: clients must
+ # drop this tool from ``tools/list``.
+ "name": "broken_header_tool",
+ "description": "Has an invalid x-mcp-header annotation",
+ "inputSchema": {
+ "type": "object",
+ "properties": {"ratio": {"type": "number", "x-mcp-header": "Ratio"}},
+ },
+ },
+]
+MODERN_TEST_TOOLS = TEST_TOOLS + MODERN_EXTRA_TOOLS
-def _handle_initialize(params: dict) -> dict:
- return {
- "protocolVersion": "2025-03-26",
- "capabilities": {"tools": {"listChanged": False}},
- "serverInfo": {"name": "test-mcp-server", "version": "1.0.0"},
- }
-
+_CONFIRMATION_STATE = "confirm-me"
-def _handle_tools_list(params: dict) -> dict:
- return {"tools": TEST_TOOLS}
-
-def _handle_tools_call(params: dict) -> dict:
+def _tool_result(params: dict) -> dict:
tool_name = params.get("name", "")
arguments = params.get("arguments", {})
@@ -96,6 +158,32 @@ def _handle_tools_call(params: dict) -> dict:
"content": [{"type": "text", "text": message}],
}
+ elif tool_name == "execute_sql":
+ return {
+ "content": [
+ {
+ "type": "text",
+ "text": json.dumps({"region": arguments.get("region"), "rows": 1}),
+ }
+ ],
+ }
+
+ elif tool_name == "needs_confirmation":
+ if params.get("requestState") == _CONFIRMATION_STATE:
+ return {"content": [{"type": "text", "text": "confirmed"}]}
+ return {"resultType": "input_required", "requestState": _CONFIRMATION_STATE}
+
+ elif tool_name == "needs_elicitation":
+ return {
+ "resultType": "input_required",
+ "inputRequests": {
+ "login": {
+ "method": "elicitation/create",
+ "params": {"mode": "form", "message": "Who are you?"},
+ }
+ },
+ }
+
else:
return {
"content": [{"type": "text", "text": f"Unknown tool: {tool_name}"}],
@@ -103,6 +191,25 @@ def _handle_tools_call(params: dict) -> dict:
}
+# ─────────────────────────── legacy era ───────────────────────────
+
+
+def _handle_initialize(params: dict) -> dict:
+ return {
+ "protocolVersion": LEGACY_PROTOCOL_VERSION,
+ "capabilities": {"tools": {"listChanged": False}},
+ "serverInfo": dict(SERVER_INFO),
+ }
+
+
+def _handle_tools_list(params: dict) -> dict:
+ return {"tools": TEST_TOOLS}
+
+
+def _handle_tools_call(params: dict) -> dict:
+ return _tool_result(params)
+
+
HANDLERS = {
"initialize": _handle_initialize,
"tools/list": _handle_tools_list,
@@ -110,10 +217,150 @@ HANDLERS = {
}
+def _jsonrpc_error(request_id, code: int, message: str, data=None, *, status=200):
+ error: dict = {"code": code, "message": message}
+ if data is not None:
+ error["data"] = data
+ return web.json_response(
+ {"jsonrpc": "2.0", "error": error, "id": request_id}, status=status
+ )
+
+
+def _legacy_response(app: web.Application, request: web.Request, body: dict):
+ method = body.get("method", "")
+ params = body.get("params", {})
+ request_id = body.get("id")
+
+ if app["sessions_enabled"] and method != "initialize":
+ session_id = request.headers.get(HEADER_SESSION_ID)
+ if not session_id or session_id not in app["sessions"]:
+ # What the reference SDKs do for a request outside a session:
+ # a plain-text 400 with no JSON-RPC body.
+ return web.Response(status=400, text="Bad Request: Missing session ID")
+
+ handler = HANDLERS.get(method)
+ if not handler:
+ return _jsonrpc_error(
+ request_id, ERROR_METHOD_NOT_FOUND, f"Method not found: {method}"
+ )
+
+ result = handler(params)
+ response = web.json_response({"jsonrpc": "2.0", "result": result, "id": request_id})
+ if method == "initialize" and app["sessions_enabled"]:
+ session_id = uuid.uuid4().hex
+ app["sessions"].add(session_id)
+ response.headers[HEADER_SESSION_ID] = session_id
+ return response
+
+
+# ─────────────────────────── modern era ───────────────────────────
+
+
+def _modern_result(result: dict) -> dict:
+ result = dict(result)
+ result.setdefault("resultType", "complete")
+ result.setdefault("_meta", {})[META_SERVER_INFO] = dict(SERVER_INFO)
+ return result
+
+
+def _modern_response(app: web.Application, request: web.Request, body: dict):
+ method = body.get("method", "")
+ params = body.get("params") or {}
+ request_id = body.get("id")
+ meta = params.get("_meta") or {}
+ version = meta.get(META_PROTOCOL_VERSION)
+
+ if not version or META_CLIENT_CAPABILITIES not in meta:
+ return _jsonrpc_error(
+ request_id,
+ ERROR_INVALID_PARAMS,
+ "Missing required _meta fields",
+ status=400,
+ )
+ if version not in app["supported_versions"]:
+ return _jsonrpc_error(
+ request_id,
+ ERROR_UNSUPPORTED_PROTOCOL_VERSION,
+ "Unsupported protocol version",
+ {"supported": list(app["supported_versions"]), "requested": version},
+ status=400,
+ )
+
+ def mismatch(detail: str):
+ return _jsonrpc_error(
+ request_id,
+ ERROR_HEADER_MISMATCH,
+ f"Header mismatch: {detail}",
+ status=400,
+ )
+
+ if request.headers.get(HEADER_PROTOCOL_VERSION) != version:
+ return mismatch(f"{HEADER_PROTOCOL_VERSION} missing or wrong")
+ if request.headers.get(HEADER_METHOD) != method:
+ return mismatch(f"{HEADER_METHOD} missing or wrong")
+ if method == "tools/call":
+ name_header = request.headers.get(HEADER_NAME)
+ if name_header is None or decode_header_value(name_header) != params.get(
+ "name"
+ ):
+ return mismatch(f"{HEADER_NAME} missing or wrong")
+ if params.get("name") == "execute_sql":
+ region = (params.get("arguments") or {}).get("region")
+ header = request.headers.get(f"{HEADER_PARAM_PREFIX}Region")
+ if region is not None and (
+ header is None or decode_header_value(header) != str(region)
+ ):
+ return mismatch(f"{HEADER_PARAM_PREFIX}Region missing or wrong")
+
+ if method == "server/discover":
+ result = {
+ "supportedVersions": list(app["supported_versions"]),
+ "capabilities": {"tools": {"listChanged": False}},
+ "instructions": "Test server",
+ "ttlMs": 3_600_000,
+ "cacheScope": "public",
+ }
+ elif method == "tools/list":
+ result = {"tools": MODERN_TEST_TOOLS, "ttlMs": 300_000, "cacheScope": "public"}
+ elif method == "tools/call":
+ result = _tool_result(params)
+ else:
+ return _jsonrpc_error(
+ request_id,
+ ERROR_METHOD_NOT_FOUND,
+ f"Method not found: {method} "
+ f"(supported protocol versions: {', '.join(app['supported_versions'])})",
+ status=404,
+ )
+
+ return web.json_response(
+ {"jsonrpc": "2.0", "result": _modern_result(result), "id": request_id}
+ )
+
+
+# ─────────────────────────── app wiring ───────────────────────────
+
+
+def _as_sse(response: web.Response) -> web.Response:
+ """Re-wrap a JSON reply as a single-event SSE stream."""
+ payload = response.text
+ if response.content_type != "application/json" or payload is None:
+ return response
+ return web.Response(
+ status=response.status,
+ headers={
+ k: v for k, v in response.headers.items() if k.lower() != "content-type"
+ },
+ text=f"event: message\ndata: {payload}\n\n",
+ content_type="text/event-stream",
+ )
+
+
async def handle_mcp_request(request: web.Request) -> web.Response:
"""Handle incoming MCP JSON-RPC 2.0 requests."""
+ app = request.app
# Check auth if configured
- expected_token = request.app.get("auth_token")
+ expected_token = app.get("auth_token")
if expected_token:
auth_header = request.headers.get("Authorization", "")
if auth_header != f"Bearer {expected_token}":
@@ -127,36 +374,71 @@ async def handle_mcp_request(request: web.Request) -> web.Response:
)
body = await request.json()
+ app["requests"].append(
+ {
+ "method": body.get("method"),
+ "params": body.get("params") or {},
+ "headers": dict(request.headers),
+ }
+ )
# Handle notifications (no id field) — just acknowledge
if "id" not in body:
return web.Response(status=202)
- method = body.get("method", "")
- params = body.get("params", {})
- request_id = body.get("id")
+ era = app["era"]
+ params = body.get("params") or {}
+ is_modern_request = META_PROTOCOL_VERSION in (params.get("_meta") or {})
+ if era == "modern" or (era == "dual" and is_modern_request):
+ response = _modern_response(app, request, body)
+ else:
+ response = _legacy_response(app, request, body)
- handler = HANDLERS.get(method)
- if not handler:
- return web.json_response(
- {
- "jsonrpc": "2.0",
- "error": {
- "code": -32601,
- "message": f"Method not found: {method}",
- },
- "id": request_id,
- }
- )
+ if app["sse"]:
+ response = _as_sse(response)
+ return response
+
+
+async def handle_mcp_delete(request: web.Request) -> web.Response:
+ """Legacy session termination; modern servers answer 405."""
+ app = request.app
+ if app["era"] == "modern":
+ return web.Response(status=405)
+ session_id = request.headers.get(HEADER_SESSION_ID)
+ app["deleted_sessions"].append(session_id)
+ app["sessions"].discard(session_id)
+ return web.Response(status=200)
- result = handler(params)
- return web.json_response({"jsonrpc": "2.0", "result": result, "id": request_id})
+def create_test_mcp_app(
+ auth_token: str | None = None,
+ era: Literal["legacy", "modern", "dual"] = "legacy",
+ *,
+ sse: bool = False,
+ sessions: bool = False,
+ supported_versions: tuple[str, ...] = (MODERN_PROTOCOL_VERSION,),
+) -> web.Application:
+ """Create an aiohttp app that acts as an MCP server.
-def create_test_mcp_app(auth_token: str | None = None) -> web.Application:
- """Create an aiohttp app that acts as an MCP server."""
+ Args:
+ auth_token: Require this Bearer token on every request.
+ era: ``"legacy"``, ``"modern"`` or ``"dual"``.
+ sse: Return every reply as ``text/event-stream``.
+ sessions: (legacy) mint ``Mcp-Session-Id`` on initialize and require
+ it afterwards, answering session-less requests with a plain-text
+ ``400`` like the reference SDKs.
+ supported_versions: (modern) protocol versions advertised/accepted.
+ """
app = web.Application()
app.router.add_post("/mcp", handle_mcp_request)
+ app.router.add_delete("/mcp", handle_mcp_delete)
+ app["era"] = era
+ app["sse"] = sse
+ app["sessions_enabled"] = sessions
+ app["supported_versions"] = tuple(supported_versions)
+ app["sessions"] = set()
+ app["deleted_sessions"] = []
+ app["requests"] = []
if auth_token:
app["auth_token"] = auth_token
return app
diff --git a/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool.py b/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool.py
index 29fc4fce5f..50d018a0fa 100644
--- a/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool.py
+++ b/autogpt_platform/backend/backend/copilot/tools/run_mcp_tool.py
@@ -342,6 +342,9 @@ class RunMCPToolTool(BaseTool):
message="An unexpected error occurred connecting to the MCP server. Please try again.",
session_id=session_id,
)
+ finally:
+ # Release any legacy session; a no-op on stateless servers.
+ await client.close()
async def _discover_tools(
self,
@@ -421,6 +424,7 @@ class RunMCPToolTool(BaseTool):
Single-item responses are unwrapped from the list; multiple items are
returned as a list; empty content returns None.
"""
+ input_schema: dict[str, Any] | None = None
if _args_contain_file_ref(tool_arguments):
input_schema = await self._lookup_tool_schema(client, tool_name)
try:
@@ -436,7 +440,9 @@ class RunMCPToolTool(BaseTool):
session_id=session_id,
)
- result = await client.call_tool(tool_name, tool_arguments)
+ result = await client.call_tool(
+ tool_name, tool_arguments, input_schema=input_schema
+ )
if result.is_error:
error_text = " ".join(
diff --git a/autogpt_platform/backend/backend/copilot/tools/test_session_dry_run.py b/autogpt_platform/backend/backend/copilot/tools/test_session_dry_run.py
index 9060aa983c..aa18256c0e 100644
--- a/autogpt_platform/backend/backend/copilot/tools/test_session_dry_run.py
+++ b/autogpt_platform/backend/backend/copilot/tools/test_session_dry_run.py
@@ -393,7 +393,9 @@ class TestRunMCPToolToolSessionDryRun:
# Execution should proceed
mock_client.initialize.assert_called_once()
- mock_client.call_tool.assert_called_once_with("some_tool", {"key": "value"})
+ mock_client.call_tool.assert_called_once_with(
+ "some_tool", {"key": "value"}, input_schema=None
+ )
assert isinstance(result, MCPToolOutputResponse)
assert result.success is True
diff --git a/autogpt_platform/backend/backend/util/architecture_test.py b/autogpt_platform/backend/backend/util/architecture_test.py
index 249ed797ac..c0bada90a3 100644
--- a/autogpt_platform/backend/backend/util/architecture_test.py
+++ b/autogpt_platform/backend/backend/util/architecture_test.py
@@ -120,7 +120,6 @@ _DATACLASS_KNOWN_OFFENDERS = frozenset(
"api/features/store/content_handlers.py",
"api/features/store/hybrid_search.py",
"blocks/codex.py",
- "blocks/mcp/client.py",
"copilot/baseline/service.py",
"copilot/bot/adapters/base.py",
"copilot/bot/bot_backend.py",
diff --git a/autogpt_platform/backend/backend/util/request.py b/autogpt_platform/backend/backend/util/request.py
index 78555c878e..20da177b32 100644
--- a/autogpt_platform/backend/backend/util/request.py
+++ b/autogpt_platform/backend/backend/util/request.py
@@ -361,6 +361,25 @@ class Response:
def ok(self) -> bool:
return 200 <= self.status < 300
+ def raise_for_status(self) -> None:
+ """Raise the same error ``Requests(raise_for_status=True)`` would have.
+
+ For callers that need to inspect an error body before deciding what a
+ status means, and only then want the standard exception.
+ """
+ if self.status >= 400:
+ raise http_status_error(self.status, self.reason, self.content)
+
+
+def http_status_error(status: int, reason: str | None, body: bytes) -> Exception:
+ """Build the exception ``Requests`` raises for an HTTP error status."""
+ message = f"HTTP {status} Error: {reason}, Body: {body.decode(errors='replace')}"
+ if 400 <= status <= 499:
+ return HTTPClientError(message, status)
+ if 500 <= status <= 599:
+ return HTTPServerError(message, status)
+ return Exception(message)
+
def _return_last_result(retry_state: RetryCallState) -> "Response":
"""
@@ -550,16 +569,9 @@ class Requests:
response.raise_for_status()
except ClientResponseError as e:
body = await response.read()
- error_message = f"HTTP {response.status} Error: {response.reason}, Body: {body.decode(errors='replace')}"
-
- # Raise specific exceptions based on status code range
- if 400 <= response.status <= 499:
- raise HTTPClientError(error_message, response.status) from e
- elif 500 <= response.status <= 599:
- raise HTTPServerError(error_message, response.status) from e
- else:
- # Generic fallback for other HTTP errors
- raise Exception(error_message) from e
+ raise http_status_error(
+ response.status, response.reason, body
+ ) from e
# If allowed and a redirect is received, follow the redirect manually
if allow_redirects and response.status in (301, 302, 303, 307, 308):
diff --git a/autogpt_platform/frontend/src/app/(platform)/auth/integrations/mcp_callback/__tests__/route.test.ts b/autogpt_platform/frontend/src/app/(platform)/auth/integrations/mcp_callback/__tests__/route.test.ts
new file mode 100644
index 0000000000..291ace6384
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/auth/integrations/mcp_callback/__tests__/route.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+
+import { GET } from "../route";
+
+const origin = "http://localhost:3000";
+
+function embeddedMessage(html: string): Record<string, unknown> {
+ const match = html.match(/var msg = (\{.*?\});/);
+ if (!match) throw new Error("callback page does not embed a message");
+ return JSON.parse(match[1]);
+}
+
+describe("MCP OAuth callback route", () => {
+ it("forwards code, state and the RFC 9207 issuer to the opener", async () => {
+ const response = await GET(
+ new Request(
+ `${origin}/auth/integrations/mcp_callback?code=abc&state=xyz&iss=${encodeURIComponent("https://auth.example.com")}`,
+ ),
+ );
+ const html = await response.text();
+
+ expect(response.headers.get("Content-Type")).toBe("text/html");
+ expect(embeddedMessage(html)).toEqual({
+ success: true,
+ code: "abc",
+ state: "xyz",
+ iss: "https://auth.example.com",
+ });
+ expect(html).toContain('message_type: "mcp_oauth_result"');
+ });
+
+ it("reports a null issuer when the authorization server sends none", async () => {
+ const response = await GET(
+ new Request(
+ `${origin}/auth/integrations/mcp_callback?code=abc&state=xyz`,
+ ),
+ );
+
+ expect(embeddedMessage(await response.text())).toEqual({
+ success: true,
+ code: "abc",
+ state: "xyz",
+ iss: null,
+ });
+ });
+
+ it("reports failure when code or state is missing", async () => {
+ const response = await GET(
+ new Request(`${origin}/auth/integrations/mcp_callback?state=xyz`),
+ );
+
+ const message = embeddedMessage(await response.text());
+ expect(message.success).toBe(false);
+ expect(message.message).toContain("Missing parameters");
+ });
+
+ it("escapes script-breaking characters in query values", async () => {
+ const response = await GET(
+ new Request(
+ `${origin}/auth/integrations/mcp_callback?code=${encodeURIComponent("</script><script>alert(1)</script>")}&state=xyz`,
+ ),
+ );
+
+ const html = await response.text();
+ expect(html).not.toContain("</script><script>alert(1)");
+ expect(embeddedMessage(html).code).toBe(
+ "</script><script>alert(1)</script>",
+ );
+ });
+});
diff --git a/autogpt_platform/frontend/src/app/(platform)/auth/integrations/mcp_callback/route.ts b/autogpt_platform/frontend/src/app/(platform)/auth/integrations/mcp_callback/route.ts
index 8786a1b78c..821a2fe56a 100644
--- a/autogpt_platform/frontend/src/app/(platform)/auth/integrations/mcp_callback/route.ts
+++ b/autogpt_platform/frontend/src/app/(platform)/auth/integrations/mcp_callback/route.ts
@@ -23,10 +23,11 @@ export async function GET(request: Request) {
const { searchParams } = new URL(request.url);
const code = searchParams.get("code");
const state = searchParams.get("state");
+ const iss = searchParams.get("iss");
const success = Boolean(code && state);
const message = success
- ? { success: true, code, state }
+ ? { success: true, code, state, iss }
: {
success: false,
message: `Missing parameters: ${searchParams.toString()}`,
@@ -39,18 +40,19 @@ export async function GET(request: Request) {
<body style="font-family: system-ui, -apple-system, sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #f9fafb;">
<div style="text-align: center; max-width: 400px; padding: 2rem;">
<div id="spinner" style="margin: 0 auto 1rem; width: 32px; height: 32px; border: 3px solid #e5e7eb; border-top-color: #3b82f6; border-radius: 50%; animation: spin 0.8s linear infinite;"></div>
- <p id="status" style="color: #374151; font-size: 16px;">Completing sign-in...</p>
+ <p id="status" role="status" aria-live="polite" style="color: #374151; font-size: 16px;">Completing sign-in...</p>
</div>
<style>@keyframes spin { to { transform: rotate(360deg); } }</style>
<script>
(function() {
var msg = ${safeJsonStringify(message)};
+ var payload = { message_type: "mcp_oauth_result", success: msg.success, code: msg.code, state: msg.state, iss: msg.iss, message: msg.message };
var sent = false;
// Method 1: BroadcastChannel (reliable across tabs/popups, no opener needed)
try {
var bc = new BroadcastChannel("oauth_popup");
- bc.postMessage({ message_type: "mcp_oauth_result", success: msg.success, code: msg.code, state: msg.state, message: msg.message });
+ bc.postMessage(payload);
bc.close();
sent = true;
} catch(e) { /* BroadcastChannel not supported */ }
@@ -58,10 +60,7 @@ export async function GET(request: Request) {
// Method 2: window.opener.postMessage (fallback for same-origin popups)
try {
if (window.opener && !window.opener.closed) {
- window.opener.postMessage(
- { message_type: "mcp_oauth_result", success: msg.success, code: msg.code, state: msg.state, message: msg.message },
- window.location.origin
- );
+ window.opener.postMessage(payload, window.location.origin);
sent = true;
}
} catch(e) { /* opener not available (COOP) */ }
@@ -71,7 +70,7 @@ export async function GET(request: Request) {
// for a single shared slot (poller destructively reads its own key).
try {
if (msg.state) {
- localStorage.setItem("oauth_popup_result_" + msg.state, JSON.stringify({ message_type: "mcp_oauth_result", ...msg }));
+ localStorage.setItem("oauth_popup_result_" + msg.state, JSON.stringify(payload));
sent = true;
}
} catch(e) { /* localStorage not available */ }
diff --git a/autogpt_platform/frontend/src/app/(platform)/build/components/MCPToolDialog.tsx b/autogpt_platform/frontend/src/app/(platform)/build/components/MCPToolDialog.tsx
index 025eec9c5e..80d5fb56a2 100644
--- a/autogpt_platform/frontend/src/app/(platform)/build/components/MCPToolDialog.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/build/components/MCPToolDialog.tsx
@@ -283,11 +283,30 @@ export function MCPToolDialog({
setOauthLoading(true);
try {
- const loginResponse = await postV2InitiateOauthLoginForAnMcpServer({
- server_url: serverUrl.trim(),
- });
- if (loginResponse.status !== 200) {
- throw getAPIResponseError(loginResponse.status, loginResponse.data);
+ // Only a 400 from the *initiate* call means "this server has no OAuth
+ // to offer" and justifies the manual-token fallback. A 400 later in
+ // the flow is a rejected authorization response — a failed issuer
+ // check, say — and must surface as the error it is rather than an
+ // invitation to paste a credential instead.
+ let loginResponse: Awaited<
+ ReturnType<typeof postV2InitiateOauthLoginForAnMcpServer>
+ >;
+ try {
+ loginResponse = await postV2InitiateOauthLoginForAnMcpServer({
+ server_url: serverUrl.trim(),
+ });
+ if (loginResponse.status !== 200) {
+ throw getAPIResponseError(loginResponse.status, loginResponse.data);
+ }
+ } catch (error: unknown) {
+ if (getErrorStatus(error) === 400) {
+ setShowManualToken(true);
+ setError(
+ "This server does not support OAuth sign-in. Choose how its API credential should be sent.",
+ );
+ return;
+ }
+ throw error;
}
const { login_url, state_token } = loginResponse.data;
@@ -309,11 +328,13 @@ export function MCPToolDialog({
callbackResult = await mcpProvider.mcpOAuthCallback(
result.code,
state_token,
+ result.iss,
);
} else {
const cbResponse = await postV2ExchangeOauthCodeForMcpTokens({
code: result.code,
state_token,
+ iss: result.iss,
});
if (cbResponse.status !== 200) {
throw getAPIResponseError(cbResponse.status, cbResponse.data);
@@ -341,13 +362,7 @@ export function MCPToolDialog({
} catch (error: unknown) {
const status = getErrorStatus(error);
const message = getErrorMessage(error, "Failed to complete sign-in");
- // If server doesn't support OAuth → show manual token entry
- if (status === 400) {
- setShowManualToken(true);
- setError(
- "This server does not support OAuth sign-in. Choose how its API credential should be sent.",
- );
- } else if (message === "OAuth flow timed out") {
+ if (message === "OAuth flow timed out") {
setError("OAuth sign-in timed out. Please try again.");
} else if (status === 401 || status === 403) {
setError(
diff --git a/autogpt_platform/frontend/src/app/(platform)/build/components/__tests__/MCPToolDialog.test.tsx b/autogpt_platform/frontend/src/app/(platform)/build/components/__tests__/MCPToolDialog.test.tsx
index f10aab85dc..72fd2bd38f 100644
--- a/autogpt_platform/frontend/src/app/(platform)/build/components/__tests__/MCPToolDialog.test.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/build/components/__tests__/MCPToolDialog.test.tsx
@@ -88,6 +88,50 @@ describe("MCPToolDialog credential binding", () => {
vi.clearAllMocks();
});
+ it("surfaces a rejected authorization response instead of offering a token", async () => {
+ // The callback answers 400 when the RFC 9207 ``iss`` is missing or does
+ // not match the issuer bound at login. That is a blocked mix-up, not an
+ // unsupported server, so it must not fall back to manual token entry.
+ const {
+ postV2DiscoverAvailableToolsOnAnMcpServer,
+ postV2InitiateOauthLoginForAnMcpServer,
+ postV2ExchangeOauthCodeForMcpTokens,
+ } = await import("@/app/api/__generated__/endpoints/mcp/mcp");
+ const { openOAuthPopup } = await import("@/lib/oauth-popup");
+
+ vi.mocked(postV2DiscoverAvailableToolsOnAnMcpServer).mockResolvedValueOnce(
+ apiResponse(401, { detail: "Authentication required" }),
+ );
+ vi.mocked(postV2InitiateOauthLoginForAnMcpServer).mockResolvedValueOnce(
+ apiResponse(200, {
+ login_url: "https://auth.example.com/authorize",
+ state_token: "st",
+ }),
+ );
+ vi.mocked(openOAuthPopup).mockReturnValueOnce({
+ promise: Promise.resolve({ code: "auth-code", state: "st" }),
+ cleanup: { abort: vi.fn(), signal: new AbortController().signal },
+ popupBlocked: false,
+ fallbackBlocked: false,
+ });
+ vi.mocked(postV2ExchangeOauthCodeForMcpTokens).mockResolvedValueOnce(
+ apiResponse(400, {
+ detail:
+ "Authorization response issuer does not match the authorization server this login was started with.",
+ }),
+ );
+
+ render(<MCPToolDialog open onClose={() => {}} onConfirm={vi.fn()} />);
+ fireEvent.change(screen.getByLabelText("Server URL"), {
+ target: { value: PRIVATE_SERVER_URL },
+ });
+ fireEvent.click(screen.getByRole("button", { name: "Discover Tools" }));
+
+ expect(await screen.findByText(/issuer does not match/i)).toBeDefined();
+ expect(screen.queryByLabelText("API token")).toBeNull();
+ expect(screen.queryByText(/does not support OAuth/)).toBeNull();
+ });
+
it("attaches a manually stored credential to a tool from the same server", async () => {
const {
postV2DiscoverAvailableToolsOnAnMcpServer,
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/tools/RunMCPTool/components/MCPSetupCard/MCPSetupCard.tsx b/autogpt_platform/frontend/src/app/(platform)/copilot/tools/RunMCPTool/components/MCPSetupCard/MCPSetupCard.tsx
index 5d3cc6b9fc..b03c20ffff 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/tools/RunMCPTool/components/MCPSetupCard/MCPSetupCard.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/tools/RunMCPTool/components/MCPSetupCard/MCPSetupCard.tsx
@@ -16,13 +16,14 @@ import {
mcpAuthTokenPlaceholder,
} from "@/components/contextual/MCPAuthSchemeField/helpers";
import { useMCPAuthScheme } from "@/components/contextual/MCPAuthSchemeField/useMCPAuthScheme";
+import { isKey } from "@/lib/keyboard";
import {
detectMCPAuthScheme,
prepareMCPAuthCredential,
validateMCPAuthCredential,
type MCPAuthScheme,
} from "@/lib/mcp-auth";
-import { isKey } from "@/lib/keyboard";
+import { getAPIResponseError, getErrorStatus } from "@/lib/mcp-errors";
import { normalizeMcpUrl } from "@/lib/mcp-url";
import { openOAuthPopup } from "@/lib/oauth-popup";
import { CredentialsProvidersContext } from "@/providers/agent-credentials/credentials-provider";
@@ -172,15 +173,32 @@ export function MCPSetupCard({ output, retryInstruction }: Props) {
oauthAbortRef.current?.();
try {
- const loginRes = await postV2InitiateOauthLoginForAnMcpServer({
- server_url: serverUrl,
- });
- if (!(loginRes.status >= 200 && loginRes.status < 300)) {
- const d =
- loginRes.data && typeof loginRes.data === "object"
- ? loginRes.data
- : {};
- throw { status: loginRes.status, ...d };
+ // Only a 400 from the *initiate* call means "this server has no OAuth
+ // to offer" and justifies the manual-token fallback. A 400 from the
+ // callback is a rejected authorization response — a failed issuer
+ // check, say — and must surface as the error it is rather than an
+ // invitation to paste a credential instead.
+ let loginRes: Awaited<
+ ReturnType<typeof postV2InitiateOauthLoginForAnMcpServer>
+ >;
+ try {
+ loginRes = await postV2InitiateOauthLoginForAnMcpServer({
+ server_url: serverUrl,
+ });
+ if (!(loginRes.status >= 200 && loginRes.status < 300)) {
+ throw getAPIResponseError(loginRes.status, loginRes.data);
+ }
+ } catch (e: unknown) {
+ if (getErrorStatus(e) === 400) {
+ setConnected(false);
+ setForceDisconnected(true);
+ setShowManualToken(true);
+ setError(
+ "This server does not support OAuth sign-in. Choose how its API credential should be sent.",
+ );
+ return;
+ }
+ throw e;
}
const { login_url, state_token } = loginRes.data as {
login_url: string;
@@ -197,16 +215,19 @@ export function MCPSetupCard({ output, retryInstruction }: Props) {
const mcpProvider = allProviders?.["mcp"];
if (mcpProvider) {
- await mcpProvider.mcpOAuthCallback(result.code, state_token);
+ await mcpProvider.mcpOAuthCallback(
+ result.code,
+ state_token,
+ result.iss,
+ );
} else {
const cbRes = await postV2ExchangeOauthCodeForMcpTokens({
code: result.code,
state_token,
+ iss: result.iss,
});
if (!(cbRes.status >= 200 && cbRes.status < 300)) {
- const d =
- cbRes.data && typeof cbRes.data === "object" ? cbRes.data : {};
- throw { status: cbRes.status, ...d };
+ throw getAPIResponseError(cbRes.status, cbRes.data);
}
}
@@ -228,12 +249,7 @@ export function MCPSetupCard({ output, retryInstruction }: Props) {
// user retries.
setConnected(false);
setForceDisconnected(true);
- if (err?.status === 400) {
- setShowManualToken(true);
- setError(
- "This server does not support OAuth sign-in. Choose how its API credential should be sent.",
- );
- } else if (
+ if (
typeof err?.message === "string" &&
err.message === "OAuth flow timed out"
) {
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/tools/RunMCPTool/components/MCPSetupCard/__tests__/MCPSetupCard.test.tsx b/autogpt_platform/frontend/src/app/(platform)/copilot/tools/RunMCPTool/components/MCPSetupCard/__tests__/MCPSetupCard.test.tsx
index 09b05fa099..c9a6a2e220 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/tools/RunMCPTool/components/MCPSetupCard/__tests__/MCPSetupCard.test.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/tools/RunMCPTool/components/MCPSetupCard/__tests__/MCPSetupCard.test.tsx
@@ -199,6 +199,54 @@ describe("MCPSetupCard", () => {
expect(screen.getByText(/does not support OAuth/)).toBeDefined();
});
+ it("surfaces a rejected authorization response instead of offering a token", async () => {
+ // The callback answers 400 when the RFC 9207 ``iss`` is missing or does
+ // not match the issuer bound at login. That is a blocked mix-up, not an
+ // unsupported server, so it must not invite the user to paste a
+ // credential in its place.
+ const { postV2InitiateOauthLoginForAnMcpServer } = await import(
+ "@/app/api/__generated__/endpoints/mcp/mcp"
+ );
+ vi.mocked(postV2InitiateOauthLoginForAnMcpServer).mockResolvedValueOnce({
+ status: 200,
+ data: {
+ login_url: "https://auth.example.com/authorize",
+ state_token: "st",
+ },
+ headers: new Headers(),
+ } as never);
+ const { openOAuthPopup } = await import("@/lib/oauth-popup");
+ vi.mocked(openOAuthPopup).mockReturnValueOnce({
+ promise: Promise.resolve({ code: "auth-code", state: "st" }),
+ cleanup: { abort: vi.fn(), signal: new AbortController().signal },
+ popupBlocked: false,
+ fallbackBlocked: false,
+ });
+ const mcpOAuthCallback = vi.fn().mockRejectedValue({
+ status: 400,
+ detail:
+ "Authorization response issuer does not match the authorization server this login was started with.",
+ });
+ const providers = {
+ mcp: { mcpOAuthCallback },
+ } as unknown as CredentialsProvidersContextType;
+
+ render(
+ <CredentialsProvidersContext.Provider value={providers}>
+ <MCPSetupCard output={makeSetupOutput()} />
+ </CredentialsProvidersContext.Provider>,
+ );
+ fireEvent.click(
+ screen.getByRole("button", { name: /connect example\.com/i }),
+ );
+
+ await waitFor(() => {
+ expect(screen.getByText(/issuer does not match/i)).toBeDefined();
+ });
+ expect(screen.queryByPlaceholderText(manualTokenPlaceholder)).toBeNull();
+ expect(screen.queryByText(/does not support OAuth/)).toBeNull();
+ });
+
it("uses a unique manual credential input id for each mounted card", async () => {
const { postV2InitiateOauthLoginForAnMcpServer } = await import(
"@/app/api/__generated__/endpoints/mcp/mcp"
@@ -528,6 +576,56 @@ describe("MCPSetupCard", () => {
});
});
+ it("forwards the authorization response issuer to the credentials provider", async () => {
+ const { postV2InitiateOauthLoginForAnMcpServer } = await import(
+ "@/app/api/__generated__/endpoints/mcp/mcp"
+ );
+ vi.mocked(postV2InitiateOauthLoginForAnMcpServer).mockResolvedValueOnce({
+ status: 200,
+ data: {
+ login_url: "https://auth.example.com/authorize",
+ state_token: "st",
+ },
+ headers: new Headers(),
+ } as never);
+ const { openOAuthPopup } = await import("@/lib/oauth-popup");
+ vi.mocked(openOAuthPopup).mockReturnValueOnce({
+ promise: Promise.resolve({
+ code: "auth-code",
+ state: "st",
+ iss: "https://auth.example.com",
+ }),
+ cleanup: { abort: vi.fn(), signal: new AbortController().signal },
+ popupBlocked: false,
+ fallbackBlocked: false,
+ });
+ const mcpOAuthCallback = vi.fn().mockResolvedValue({
+ id: "cred-1",
+ provider: "mcp",
+ type: "oauth2",
+ });
+ const providers = {
+ mcp: { mcpOAuthCallback },
+ } as unknown as CredentialsProvidersContextType;
+
+ render(
+ <CredentialsProvidersContext.Provider value={providers}>
+ <MCPSetupCard output={makeSetupOutput()} />
+ </CredentialsProvidersContext.Provider>,
+ );
+ fireEvent.click(
+ screen.getByRole("button", { name: /connect example\.com/i }),
+ );
+
+ await waitFor(() => {
+ expect(mcpOAuthCallback).toHaveBeenCalledWith(
+ "auth-code",
+ "st",
+ "https://auth.example.com",
+ );
+ });
+ });
+
it("shows generic error message when OAuth callback fails with a non-400 status", async () => {
const { postV2InitiateOauthLoginForAnMcpServer } = await import(
"@/app/api/__generated__/endpoints/mcp/mcp"
@@ -785,6 +883,7 @@ describe("MCPSetupCard", () => {
expect(latestProviderCallback).toHaveBeenCalledWith(
"latest-code",
"latest-state",
+ undefined,
);
expect(latestOnSend).toHaveBeenCalledWith("Latest retry instruction");
});
diff --git a/autogpt_platform/frontend/src/app/api/openapi.json b/autogpt_platform/frontend/src/app/api/openapi.json
index 03946d4963..6eaebb8a8d 100644
--- a/autogpt_platform/frontend/src/app/api/openapi.json
+++ b/autogpt_platform/frontend/src/app/api/openapi.json
@@ -23016,6 +23016,11 @@
"type": "string",
"title": "State Token",
"description": "State token for CSRF verification"
+ },
+ "iss": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Iss",
+ "description": "Issuer identifier from the authorization response (RFC 9207). Must match the authorization server discovered at login; required when that server advertises `authorization_response_iss_parameter_supported`."
}
},
"type": "object",
diff --git a/autogpt_platform/frontend/src/components/contextual/CredentialsInput/useCredentialsInput.ts b/autogpt_platform/frontend/src/components/contextual/CredentialsInput/useCredentialsInput.ts
index 0639a17b7c..a83b637d85 100644
--- a/autogpt_platform/frontend/src/components/contextual/CredentialsInput/useCredentialsInput.ts
+++ b/autogpt_platform/frontend/src/components/contextual/CredentialsInput/useCredentialsInput.ts
@@ -309,7 +309,7 @@ export function useCredentialsInput({
// Exchange code for tokens via the provider (updates credential cache)
const credentialResult = isMCP
- ? await mcpOAuthCallback(result.code, state_token)
+ ? await mcpOAuthCallback(result.code, state_token, result.iss)
: await oAuthCallback(result.code, result.state);
// Check if the credential's scopes match the required scopes (skip for MCP)
diff --git a/autogpt_platform/frontend/src/components/contextual/IntegrationsPanel/components/ConnectServiceDialog/components/DetailView/McpConnectPanel.tsx b/autogpt_platform/frontend/src/components/contextual/IntegrationsPanel/components/ConnectServiceDialog/components/DetailView/McpConnectPanel.tsx
index bf6ef303a5..c7b7df0214 100644
--- a/autogpt_platform/frontend/src/components/contextual/IntegrationsPanel/components/ConnectServiceDialog/components/DetailView/McpConnectPanel.tsx
+++ b/autogpt_platform/frontend/src/components/contextual/IntegrationsPanel/components/ConnectServiceDialog/components/DetailView/McpConnectPanel.tsx
@@ -129,6 +129,7 @@ export function McpConnectPanel({ onSuccess }: Props) {
const exchanged = await postV2ExchangeOauthCodeForMcpTokens({
code: result.code,
state_token,
+ iss: result.iss,
});
if (exchanged.status !== 200) {
throw getAPIResponseError(exchanged.status, exchanged.data);
diff --git a/autogpt_platform/frontend/src/lib/oauth-popup.ts b/autogpt_platform/frontend/src/lib/oauth-popup.ts
index ef1a952774..7d4ec84d2f 100644
--- a/autogpt_platform/frontend/src/lib/oauth-popup.ts
+++ b/autogpt_platform/frontend/src/lib/oauth-popup.ts
@@ -19,6 +19,8 @@ export const OAUTH_ERROR_POPUP_BLOCKED_NO_TAB =
export type OAuthPopupResult = {
code: string;
state: string;
+ /** RFC 9207 issuer identifier from the authorization response, if sent. */
+ iss?: string;
};
export type OAuthPopupOptions = {
@@ -215,7 +217,11 @@ export function openOAuthPopup(
if (!data.success) {
reject(new Error(data.message || "OAuth authentication failed"));
} else {
- resolve({ code: data.code, state: data.state });
+ resolve({
+ code: data.code,
+ state: data.state,
+ iss: typeof data.iss === "string" ? data.iss : undefined,
+ });
}
controller.abort("completed");
diff --git a/autogpt_platform/frontend/src/providers/agent-credentials/credentials-provider.tsx b/autogpt_platform/frontend/src/providers/agent-credentials/credentials-provider.tsx
index 4eee51f484..3c3c3a226b 100644
--- a/autogpt_platform/frontend/src/providers/agent-credentials/credentials-provider.tsx
+++ b/autogpt_platform/frontend/src/providers/agent-credentials/credentials-provider.tsx
@@ -48,6 +48,7 @@ export type CredentialsProviderData = {
mcpOAuthCallback: (
code: string,
state_token: string,
+ iss?: string,
) => Promise<CredentialsMetaResponse>;
/** Stores a manually entered MCP credential for a server without OAuth. */
mcpStoreToken: (
@@ -170,11 +171,13 @@ export default function CredentialsProvider({
async (
code: string,
state_token: string,
+ iss?: string,
): Promise<CredentialsMetaResponse> => {
try {
const response = await postV2ExchangeOauthCodeForMcpTokens({
code,
state_token,
+ iss,
});
if (response.status !== 200) throw response.data;
const credsMeta: CredentialsMetaResponse = {
diff --git a/docs/integrations/block-integrations/llm.md b/docs/integrations/block-integrations/llm.md
index aee1851d2d..8629f37934 100644
--- a/docs/integrations/block-integrations/llm.md
+++ b/docs/integrations/block-integrations/llm.md
@@ -65,7 +65,7 @@ The result routes data to yes_output or no_output, enabling intelligent branchin
| condition | A plaintext English description of the condition to evaluate | str | Yes |
| yes_value | (Optional) Value to output if the condition is true. If not provided, input_value will be used. | Yes Value | No |
| no_value | (Optional) Value to output if the condition is false. If not provided, input_value will be used. | No Value | No |
-| model | The language model to use for evaluating the condition. | "o3-mini" \| "o3-2025-04-16" \| "gpt-5.2-2025-12-11" \| "gpt-5.1-2025-11-13" \| "gpt-5-2025-08-07" \| "gpt-5-mini-2025-08-07" \| "o4-mini" \| "o3-pro" \| "o1" \| "o1-mini" \| "gpt-6-astra" \| "gpt-5.6-sol" \| "gpt-5.6-terra" \| "gpt-5.6-luna" \| "gpt-5.5-2026-04-23" \| "gpt-5.5-pro" \| "gpt-5.4-2026-03-05" \| "gpt-5.4-mini-2026-03-17" \| "gpt-5.4-nano-2026-03-17" \| "gpt-5.4-pro" \| "gpt-5.3-chat-latest" \| "gpt-5.3-codex" \| "gpt-5.2-pro" \| "gpt-5.1-codex" \| "gpt-5-pro" \| "gpt-4.1-nano" \| "gpt-5-nano-2025-08-07" \| "gpt-5-chat-latest" \| "gpt-4.1-2025-04-14" \| "gpt-4.1-mini-2025-04-14" \| "gpt-4o-mini" \| "gpt-4o" \| "claude-opus-4-5-20251101" \| "claude-sonnet-4-5-20250929" \| "claude-haiku-4-5-20251001" \| "claude-opus-4-6" \| "claude-opus-4-7" \| "claude-opus-5" \| "claude-sonnet-4-6" \| "claude-sonnet-5" \| "meta-llama/Llama-3.3-70B-Instruct-Turbo" \| "llama-3.3-70b-versatile" \| "llama-3.1-8b-instant" \| "llama3.3" \| "llama3.2" \| "llama3" \| "llama3.1:405b" \| "dolphin-mistral:latest" \| "openai/gpt-oss-120b" \| "openai/gpt-oss-20b" \| "google/gemini-2.5-pro" \| "google/gemini-3.1-pro-preview" \| "google/gemini-3-flash-preview" \| "google/gemini-2.5-flash" \| "google/gemini-2.0-flash-001" \| "google/gemini-3.1-flash-lite-preview" \| "google/gemini-2.5-flash-lite" \| "google/gemini-2.0-flash-lite-001" \| "mistralai/mistral-large-2512" \| "mistralai/mistral-medium-3.1" \| "mistralai/mistral-small-3.2-24b-instruct" \| "mistralai/codestral-2508" \| "cohere/command-a-03-2025" \| "cohere/command-a-translate-08-2025" \| "cohere/command-a-reasoning-08-2025" \| "cohere/command-a-vision-07-2025" \| "deepseek/deepseek-chat" \| "deepseek/deepseek-r1-0528" \| "perplexity/sonar" \| "perplexity/sonar-pro" \| "perplexity/sonar-reasoning-pro" \| "perplexity/sonar-deep-research" \| "nousresearch/hermes-3-llama-3.1-405b" \| "nousresearch/hermes-3-llama-3.1-70b" \| "amazon/nova-lite-v1" \| "amazon/nova-micro-v1" \| "amazon/nova-pro-v1" \| "microsoft/phi-4" \| "gryphe/mythomax-l2-13b" \| "meta-llama/llama-4-scout" \| "meta-llama/llama-4-maverick" \| "x-ai/grok-3" \| "x-ai/grok-4" \| "x-ai/grok-4-fast" \| "x-ai/grok-4.1-fast" \| "x-ai/grok-4.20" \| "x-ai/grok-4.20-multi-agent" \| "x-ai/grok-code-fast-1" \| "moonshotai/kimi-k2.5" \| "moonshotai/kimi-k2.6" \| "moonshotai/kimi-k2-thinking" \| "moonshotai/kimi-k3" \| "qwen/qwen3-235b-a22b-thinking-2507" \| "qwen/qwen3-coder" \| "z-ai/glm-4.6" \| "z-ai/glm-4.6v" \| "z-ai/glm-4.7" \| "z-ai/glm-4.7-flash" \| "z-ai/glm-5" \| "z-ai/glm-5-turbo" \| "z-ai/glm-5v-turbo" \| "Llama-4-Scout-17B-16E-Instruct-FP8" \| "Llama-4-Maverick-17B-128E-Instruct-FP8" \| "Llama-3.3-8B-Instruct" \| "Llama-3.3-70B-Instruct" \| "v0-1.5-md" \| "v0-1.5-lg" \| "v0-1.0-md" | No |
+| model | The language model to use for evaluating the condition. | "o3-mini" \| "o3-2025-04-16" \| "gpt-5.2-2025-12-11" \| "gpt-5.1-2025-11-13" \| "gpt-5-2025-08-07" \| "gpt-5-mini-2025-08-07" \| "o4-mini" \| "o3-pro" \| "o1" \| "o1-mini" \| "gpt-6-astra" \| "gpt-5.6-sol" \| "gpt-5.6-terra" \| "gpt-5.6-luna" \| "gpt-5.5-2026-04-23" \| "gpt-5.5-pro" \| "gpt-5.4-2026-03-05" \| "gpt-5.4-mini-2026-03-17" \| "gpt-5.4-nano-2026-03-17" \| "gpt-5.4-pro" \| "gpt-5.3-chat-latest" \| "gpt-5.3-codex" \| "gpt-5.2-pro" \| "gpt-5.1-codex" \| "gpt-5-pro" \| "gpt-4.1-nano" \| "gpt-5-nano-2025-08-07" \| "gpt-5-chat-latest" \| "gpt-4.1-2025-04-14" \| "gpt-4.1-mini-2025-04-14" \| "gpt-4o-mini" \| "gpt-4o" \| "claude-opus-4-5-20251101" \| "claude-sonnet-4-5-20250929" \| "claude-haiku-4-5-20251001" \| "claude-opus-4-6" \| "claude-opus-4-7" \| "claude-opus-5" \| "claude-sonnet-4-6" \| "claude-sonnet-5" \| "claude-fable-5-1" \| "meta-llama/Llama-3.3-70B-Instruct-Turbo" \| "llama-3.3-70b-versatile" \| "llama-3.1-8b-instant" \| "llama3.3" \| "llama3.2" \| "llama3" \| "llama3.1:405b" \| "dolphin-mistral:latest" \| "openai/gpt-oss-120b" \| "openai/gpt-oss-20b" \| "google/gemini-2.5-pro" \| "google/gemini-3.1-pro-preview" \| "google/gemini-3-flash-preview" \| "google/gemini-2.5-flash" \| "google/gemini-2.0-flash-001" \| "google/gemini-3.1-flash-lite-preview" \| "google/gemini-2.5-flash-lite" \| "google/gemini-2.0-flash-lite-001" \| "mistralai/mistral-large-2512" \| "mistralai/mistral-medium-3.1" \| "mistralai/mistral-small-3.2-24b-instruct" \| "mistralai/codestral-2508" \| "cohere/command-a-03-2025" \| "cohere/command-a-translate-08-2025" \| "cohere/command-a-reasoning-08-2025" \| "cohere/command-a-vision-07-2025" \| "deepseek/deepseek-chat" \| "deepseek/deepseek-r1-0528" \| "perplexity/sonar" \| "perplexity/sonar-pro" \| "perplexity/sonar-reasoning-pro" \| "perplexity/sonar-deep-research" \| "nousresearch/hermes-3-llama-3.1-405b" \| "nousresearch/hermes-3-llama-3.1-70b" \| "amazon/nova-lite-v1" \| "amazon/nova-micro-v1" \| "amazon/nova-pro-v1" \| "microsoft/phi-4" \| "gryphe/mythomax-l2-13b" \| "meta-llama/llama-4-scout" \| "meta-llama/llama-4-maverick" \| "x-ai/grok-3" \| "x-ai/grok-4" \| "x-ai/grok-4-fast" \| "x-ai/grok-4.1-fast" \| "x-ai/grok-4.20" \| "x-ai/grok-4.20-multi-agent" \| "x-ai/grok-code-fast-1" \| "moonshotai/kimi-k2.5" \| "moonshotai/kimi-k2.6" \| "moonshotai/kimi-k2-thinking" \| "moonshotai/kimi-k3" \| "qwen/qwen3-235b-a22b-thinking-2507" \| "qwen/qwen3-coder" \| "z-ai/glm-4.6" \| "z-ai/glm-4.6v" \| "z-ai/glm-4.7" \| "z-ai/glm-4.7-flash" \| "z-ai/glm-5" \| "z-ai/glm-5-turbo" \| "z-ai/glm-5v-turbo" \| "Llama-4-Scout-17B-16E-Instruct-FP8" \| "Llama-4-Maverick-17B-128E-Instruct-FP8" \| "Llama-3.3-8B-Instruct" \| "Llama-3.3-70B-Instruct" \| "v0-1.5-md" \| "v0-1.5-lg" \| "v0-1.0-md" | No |
### Outputs
@@ -103,7 +103,7 @@ The block sends the entire conversation history to the chosen LLM, including sys
|-------|-------------|------|----------|
| prompt | The prompt to send to the language model. | str | No |
| messages | List of messages in the conversation. | List[Any] | Yes |
-| model | The language model to use for the conversation. | "o3-mini" \| "o3-2025-04-16" \| "gpt-5.2-2025-12-11" \| "gpt-5.1-2025-11-13" \| "gpt-5-2025-08-07" \| "gpt-5-mini-2025-08-07" \| "o4-mini" \| "o3-pro" \| "o1" \| "o1-mini" \| "gpt-6-astra" \| "gpt-5.6-sol" \| "gpt-5.6-terra" \| "gpt-5.6-luna" \| "gpt-5.5-2026-04-23" \| "gpt-5.5-pro" \| "gpt-5.4-2026-03-05" \| "gpt-5.4-mini-2026-03-17" \| "gpt-5.4-nano-2026-03-17" \| "gpt-5.4-pro" \| "gpt-5.3-chat-latest" \| "gpt-5.3-codex" \| "gpt-5.2-pro" \| "gpt-5.1-codex" \| "gpt-5-pro" \| "gpt-4.1-nano" \| "gpt-5-nano-2025-08-07" \| "gpt-5-chat-latest" \| "gpt-4.1-2025-04-14" \| "gpt-4.1-mini-2025-04-14" \| "gpt-4o-mini" \| "gpt-4o" \| "claude-opus-4-5-20251101" \| "claude-sonnet-4-5-20250929" \| "claude-haiku-4-5-20251001" \| "claude-opus-4-6" \| "claude-opus-4-7" \| "claude-opus-5" \| "claude-sonnet-4-6" \| "claude-sonnet-5" \| "meta-llama/Llama-3.3-70B-Instruct-Turbo" \| "llama-3.3-70b-versatile" \| "llama-3.1-8b-instant" \| "llama3.3" \| "llama3.2" \| "llama3" \| "llama3.1:405b" \| "dolphin-mistral:latest" \| "openai/gpt-oss-120b" \| "openai/gpt-oss-20b" \| "google/gemini-2.5-pro" \| "google/gemini-3.1-pro-preview" \| "google/gemini-3-flash-preview" \| "google/gemini-2.5-flash" \| "google/gemini-2.0-flash-001" \| "google/gemini-3.1-flash-lite-preview" \| "google/gemini-2.5-flash-lite" \| "google/gemini-2.0-flash-lite-001" \| "mistralai/mistral-large-2512" \| "mistralai/mistral-medium-3.1" \| "mistralai/mistral-small-3.2-24b-instruct" \| "mistralai/codestral-2508" \| "cohere/command-a-03-2025" \| "cohere/command-a-translate-08-2025" \| "cohere/command-a-reasoning-08-2025" \| "cohere/command-a-vision-07-2025" \| "deepseek/deepseek-chat" \| "deepseek/deepseek-r1-0528" \| "perplexity/sonar" \| "perplexity/sonar-pro" \| "perplexity/sonar-reasoning-pro" \| "perplexity/sonar-deep-research" \| "nousresearch/hermes-3-llama-3.1-405b" \| "nousresearch/hermes-3-llama-3.1-70b" \| "amazon/nova-lite-v1" \| "amazon/nova-micro-v1" \| "amazon/nova-pro-v1" \| "microsoft/phi-4" \| "gryphe/mythomax-l2-13b" \| "meta-llama/llama-4-scout" \| "meta-llama/llama-4-maverick" \| "x-ai/grok-3" \| "x-ai/grok-4" \| "x-ai/grok-4-fast" \| "x-ai/grok-4.1-fast" \| "x-ai/grok-4.20" \| "x-ai/grok-4.20-multi-agent" \| "x-ai/grok-code-fast-1" \| "moonshotai/kimi-k2.5" \| "moonshotai/kimi-k2.6" \| "moonshotai/kimi-k2-thinking" \| "moonshotai/kimi-k3" \| "qwen/qwen3-235b-a22b-thinking-2507" \| "qwen/qwen3-coder" \| "z-ai/glm-4.6" \| "z-ai/glm-4.6v" \| "z-ai/glm-4.7" \| "z-ai/glm-4.7-flash" \| "z-ai/glm-5" \| "z-ai/glm-5-turbo" \| "z-ai/glm-5v-turbo" \| "Llama-4-Scout-17B-16E-Instruct-FP8" \| "Llama-4-Maverick-17B-128E-Instruct-FP8" \| "Llama-3.3-8B-Instruct" \| "Llama-3.3-70B-Instruct" \| "v0-1.5-md" \| "v0-1.5-lg" \| "v0-1.0-md" | No |
+| model | The language model to use for the conversation. | "o3-mini" \| "o3-2025-04-16" \| "gpt-5.2-2025-12-11" \| "gpt-5.1-2025-11-13" \| "gpt-5-2025-08-07" \| "gpt-5-mini-2025-08-07" \| "o4-mini" \| "o3-pro" \| "o1" \| "o1-mini" \| "gpt-6-astra" \| "gpt-5.6-sol" \| "gpt-5.6-terra" \| "gpt-5.6-luna" \| "gpt-5.5-2026-04-23" \| "gpt-5.5-pro" \| "gpt-5.4-2026-03-05" \| "gpt-5.4-mini-2026-03-17" \| "gpt-5.4-nano-2026-03-17" \| "gpt-5.4-pro" \| "gpt-5.3-chat-latest" \| "gpt-5.3-codex" \| "gpt-5.2-pro" \| "gpt-5.1-codex" \| "gpt-5-pro" \| "gpt-4.1-nano" \| "gpt-5-nano-2025-08-07" \| "gpt-5-chat-latest" \| "gpt-4.1-2025-04-14" \| "gpt-4.1-mini-2025-04-14" \| "gpt-4o-mini" \| "gpt-4o" \| "claude-opus-4-5-20251101" \| "claude-sonnet-4-5-20250929" \| "claude-haiku-4-5-20251001" \| "claude-opus-4-6" \| "claude-opus-4-7" \| "claude-opus-5" \| "claude-sonnet-4-6" \| "claude-sonnet-5" \| "claude-fable-5-1" \| "meta-llama/Llama-3.3-70B-Instruct-Turbo" \| "llama-3.3-70b-versatile" \| "llama-3.1-8b-instant" \| "llama3.3" \| "llama3.2" \| "llama3" \| "llama3.1:405b" \| "dolphin-mistral:latest" \| "openai/gpt-oss-120b" \| "openai/gpt-oss-20b" \| "google/gemini-2.5-pro" \| "google/gemini-3.1-pro-preview" \| "google/gemini-3-flash-preview" \| "google/gemini-2.5-flash" \| "google/gemini-2.0-flash-001" \| "google/gemini-3.1-flash-lite-preview" \| "google/gemini-2.5-flash-lite" \| "google/gemini-2.0-flash-lite-001" \| "mistralai/mistral-large-2512" \| "mistralai/mistral-medium-3.1" \| "mistralai/mistral-small-3.2-24b-instruct" \| "mistralai/codestral-2508" \| "cohere/command-a-03-2025" \| "cohere/command-a-translate-08-2025" \| "cohere/command-a-reasoning-08-2025" \| "cohere/command-a-vision-07-2025" \| "deepseek/deepseek-chat" \| "deepseek/deepseek-r1-0528" \| "perplexity/sonar" \| "perplexity/sonar-pro" \| "perplexity/sonar-reasoning-pro" \| "perplexity/sonar-deep-research" \| "nousresearch/hermes-3-llama-3.1-405b" \| "nousresearch/hermes-3-llama-3.1-70b" \| "amazon/nova-lite-v1" \| "amazon/nova-micro-v1" \| "amazon/nova-pro-v1" \| "microsoft/phi-4" \| "gryphe/mythomax-l2-13b" \| "meta-llama/llama-4-scout" \| "meta-llama/llama-4-maverick" \| "x-ai/grok-3" \| "x-ai/grok-4" \| "x-ai/grok-4-fast" \| "x-ai/grok-4.1-fast" \| "x-ai/grok-4.20" \| "x-ai/grok-4.20-multi-agent" \| "x-ai/grok-code-fast-1" \| "moonshotai/kimi-k2.5" \| "moonshotai/kimi-k2.6" \| "moonshotai/kimi-k2-thinking" \| "moonshotai/kimi-k3" \| "qwen/qwen3-235b-a22b-thinking-2507" \| "qwen/qwen3-coder" \| "z-ai/glm-4.6" \| "z-ai/glm-4.6v" \| "z-ai/glm-4.7" \| "z-ai/glm-4.7-flash" \| "z-ai/glm-5" \| "z-ai/glm-5-turbo" \| "z-ai/glm-5v-turbo" \| "Llama-4-Scout-17B-16E-Instruct-FP8" \| "Llama-4-Maverick-17B-128E-Instruct-FP8" \| "Llama-3.3-8B-Instruct" \| "Llama-3.3-70B-Instruct" \| "v0-1.5-md" \| "v0-1.5-lg" \| "v0-1.0-md" | No |
| max_tokens | The maximum number of tokens to generate in the chat completion. | int | No |
| ollama_host | Ollama host for local models | str | No |
@@ -257,7 +257,7 @@ The block formulates a prompt based on the given focus or source data, sends it
|-------|-------------|------|----------|
| focus | The focus of the list to generate. | str | No |
| source_data | The data to generate the list from. | str | No |
-| model | The language model to use for generating the list. | "o3-mini" \| "o3-2025-04-16" \| "gpt-5.2-2025-12-11" \| "gpt-5.1-2025-11-13" \| "gpt-5-2025-08-07" \| "gpt-5-mini-2025-08-07" \| "o4-mini" \| "o3-pro" \| "o1" \| "o1-mini" \| "gpt-6-astra" \| "gpt-5.6-sol" \| "gpt-5.6-terra" \| "gpt-5.6-luna" \| "gpt-5.5-2026-04-23" \| "gpt-5.5-pro" \| "gpt-5.4-2026-03-05" \| "gpt-5.4-mini-2026-03-17" \| "gpt-5.4-nano-2026-03-17" \| "gpt-5.4-pro" \| "gpt-5.3-chat-latest" \| "gpt-5.3-codex" \| "gpt-5.2-pro" \| "gpt-5.1-codex" \| "gpt-5-pro" \| "gpt-4.1-nano" \| "gpt-5-nano-2025-08-07" \| "gpt-5-chat-latest" \| "gpt-4.1-2025-04-14" \| "gpt-4.1-mini-2025-04-14" \| "gpt-4o-mini" \| "gpt-4o" \| "claude-opus-4-5-20251101" \| "claude-sonnet-4-5-20250929" \| "claude-haiku-4-5-20251001" \| "claude-opus-4-6" \| "claude-opus-4-7" \| "claude-opus-5" \| "claude-sonnet-4-6" \| "claude-sonnet-5" \| "meta-llama/Llama-3.3-70B-Instruct-Turbo" \| "llama-3.3-70b-versatile" \| "llama-3.1-8b-instant" \| "llama3.3" \| "llama3.2" \| "llama3" \| "llama3.1:405b" \| "dolphin-mistral:latest" \| "openai/gpt-oss-120b" \| "openai/gpt-oss-20b" \| "google/gemini-2.5-pro" \| "google/gemini-3.1-pro-preview" \| "google/gemini-3-flash-preview" \| "google/gemini-2.5-flash" \| "google/gemini-2.0-flash-001" \| "google/gemini-3.1-flash-lite-preview" \| "google/gemini-2.5-flash-lite" \| "google/gemini-2.0-flash-lite-001" \| "mistralai/mistral-large-2512" \| "mistralai/mistral-medium-3.1" \| "mistralai/mistral-small-3.2-24b-instruct" \| "mistralai/codestral-2508" \| "cohere/command-a-03-2025" \| "cohere/command-a-translate-08-2025" \| "cohere/command-a-reasoning-08-2025" \| "cohere/command-a-vision-07-2025" \| "deepseek/deepseek-chat" \| "deepseek/deepseek-r1-0528" \| "perplexity/sonar" \| "perplexity/sonar-pro" \| "perplexity/sonar-reasoning-pro" \| "perplexity/sonar-deep-research" \| "nousresearch/hermes-3-llama-3.1-405b" \| "nousresearch/hermes-3-llama-3.1-70b" \| "amazon/nova-lite-v1" \| "amazon/nova-micro-v1" \| "amazon/nova-pro-v1" \| "microsoft/phi-4" \| "gryphe/mythomax-l2-13b" \| "meta-llama/llama-4-scout" \| "meta-llama/llama-4-maverick" \| "x-ai/grok-3" \| "x-ai/grok-4" \| "x-ai/grok-4-fast" \| "x-ai/grok-4.1-fast" \| "x-ai/grok-4.20" \| "x-ai/grok-4.20-multi-agent" \| "x-ai/grok-code-fast-1" \| "moonshotai/kimi-k2.5" \| "moonshotai/kimi-k2.6" \| "moonshotai/kimi-k2-thinking" \| "moonshotai/kimi-k3" \| "qwen/qwen3-235b-a22b-thinking-2507" \| "qwen/qwen3-coder" \| "z-ai/glm-4.6" \| "z-ai/glm-4.6v" \| "z-ai/glm-4.7" \| "z-ai/glm-4.7-flash" \| "z-ai/glm-5" \| "z-ai/glm-5-turbo" \| "z-ai/glm-5v-turbo" \| "Llama-4-Scout-17B-16E-Instruct-FP8" \| "Llama-4-Maverick-17B-128E-Instruct-FP8" \| "Llama-3.3-8B-Instruct" \| "Llama-3.3-70B-Instruct" \| "v0-1.5-md" \| "v0-1.5-lg" \| "v0-1.0-md" | No |
+| model | The language model to use for generating the list. | "o3-mini" \| "o3-2025-04-16" \| "gpt-5.2-2025-12-11" \| "gpt-5.1-2025-11-13" \| "gpt-5-2025-08-07" \| "gpt-5-mini-2025-08-07" \| "o4-mini" \| "o3-pro" \| "o1" \| "o1-mini" \| "gpt-6-astra" \| "gpt-5.6-sol" \| "gpt-5.6-terra" \| "gpt-5.6-luna" \| "gpt-5.5-2026-04-23" \| "gpt-5.5-pro" \| "gpt-5.4-2026-03-05" \| "gpt-5.4-mini-2026-03-17" \| "gpt-5.4-nano-2026-03-17" \| "gpt-5.4-pro" \| "gpt-5.3-chat-latest" \| "gpt-5.3-codex" \| "gpt-5.2-pro" \| "gpt-5.1-codex" \| "gpt-5-pro" \| "gpt-4.1-nano" \| "gpt-5-nano-2025-08-07" \| "gpt-5-chat-latest" \| "gpt-4.1-2025-04-14" \| "gpt-4.1-mini-2025-04-14" \| "gpt-4o-mini" \| "gpt-4o" \| "claude-opus-4-5-20251101" \| "claude-sonnet-4-5-20250929" \| "claude-haiku-4-5-20251001" \| "claude-opus-4-6" \| "claude-opus-4-7" \| "claude-opus-5" \| "claude-sonnet-4-6" \| "claude-sonnet-5" \| "claude-fable-5-1" \| "meta-llama/Llama-3.3-70B-Instruct-Turbo" \| "llama-3.3-70b-versatile" \| "llama-3.1-8b-instant" \| "llama3.3" \| "llama3.2" \| "llama3" \| "llama3.1:405b" \| "dolphin-mistral:latest" \| "openai/gpt-oss-120b" \| "openai/gpt-oss-20b" \| "google/gemini-2.5-pro" \| "google/gemini-3.1-pro-preview" \| "google/gemini-3-flash-preview" \| "google/gemini-2.5-flash" \| "google/gemini-2.0-flash-001" \| "google/gemini-3.1-flash-lite-preview" \| "google/gemini-2.5-flash-lite" \| "google/gemini-2.0-flash-lite-001" \| "mistralai/mistral-large-2512" \| "mistralai/mistral-medium-3.1" \| "mistralai/mistral-small-3.2-24b-instruct" \| "mistralai/codestral-2508" \| "cohere/command-a-03-2025" \| "cohere/command-a-translate-08-2025" \| "cohere/command-a-reasoning-08-2025" \| "cohere/command-a-vision-07-2025" \| "deepseek/deepseek-chat" \| "deepseek/deepseek-r1-0528" \| "perplexity/sonar" \| "perplexity/sonar-pro" \| "perplexity/sonar-reasoning-pro" \| "perplexity/sonar-deep-research" \| "nousresearch/hermes-3-llama-3.1-405b" \| "nousresearch/hermes-3-llama-3.1-70b" \| "amazon/nova-lite-v1" \| "amazon/nova-micro-v1" \| "amazon/nova-pro-v1" \| "microsoft/phi-4" \| "gryphe/mythomax-l2-13b" \| "meta-llama/llama-4-scout" \| "meta-llama/llama-4-maverick" \| "x-ai/grok-3" \| "x-ai/grok-4" \| "x-ai/grok-4-fast" \| "x-ai/grok-4.1-fast" \| "x-ai/grok-4.20" \| "x-ai/grok-4.20-multi-agent" \| "x-ai/grok-code-fast-1" \| "moonshotai/kimi-k2.5" \| "moonshotai/kimi-k2.6" \| "moonshotai/kimi-k2-thinking" \| "moonshotai/kimi-k3" \| "qwen/qwen3-235b-a22b-thinking-2507" \| "qwen/qwen3-coder" \| "z-ai/glm-4.6" \| "z-ai/glm-4.6v" \| "z-ai/glm-4.7" \| "z-ai/glm-4.7-flash" \| "z-ai/glm-5" \| "z-ai/glm-5-turbo" \| "z-ai/glm-5v-turbo" \| "Llama-4-Scout-17B-16E-Instruct-FP8" \| "Llama-4-Maverick-17B-128E-Instruct-FP8" \| "Llama-3.3-8B-Instruct" \| "Llama-3.3-70B-Instruct" \| "v0-1.5-md" \| "v0-1.5-lg" \| "v0-1.0-md" | No |
| max_retries | Maximum number of retries for generating a valid list. | int | No |
| force_json_output | Whether to force the LLM to produce a JSON-only response. This can increase the block's reliability, but may also reduce the quality of the response because it prohibits the LLM from reasoning before providing its JSON response. | bool | No |
| max_tokens | The maximum number of tokens to generate in the chat completion. | int | No |
@@ -424,7 +424,7 @@ The block sends the input prompt to a chosen LLM, along with any system prompts
| prompt | The prompt to send to the language model. | str | Yes |
| expected_format | Expected format of the response. If provided, the response will be validated against this format. The keys should be the expected fields in the response, and the values should be the description of the field. | Dict[str, str] | Yes |
| list_result | Whether the response should be a list of objects in the expected format. | bool | No |
-| model | The language model to use for answering the prompt. | "o3-mini" \| "o3-2025-04-16" \| "gpt-5.2-2025-12-11" \| "gpt-5.1-2025-11-13" \| "gpt-5-2025-08-07" \| "gpt-5-mini-2025-08-07" \| "o4-mini" \| "o3-pro" \| "o1" \| "o1-mini" \| "gpt-6-astra" \| "gpt-5.6-sol" \| "gpt-5.6-terra" \| "gpt-5.6-luna" \| "gpt-5.5-2026-04-23" \| "gpt-5.5-pro" \| "gpt-5.4-2026-03-05" \| "gpt-5.4-mini-2026-03-17" \| "gpt-5.4-nano-2026-03-17" \| "gpt-5.4-pro" \| "gpt-5.3-chat-latest" \| "gpt-5.3-codex" \| "gpt-5.2-pro" \| "gpt-5.1-codex" \| "gpt-5-pro" \| "gpt-4.1-nano" \| "gpt-5-nano-2025-08-07" \| "gpt-5-chat-latest" \| "gpt-4.1-2025-04-14" \| "gpt-4.1-mini-2025-04-14" \| "gpt-4o-mini" \| "gpt-4o" \| "claude-opus-4-5-20251101" \| "claude-sonnet-4-5-20250929" \| "claude-haiku-4-5-20251001" \| "claude-opus-4-6" \| "claude-opus-4-7" \| "claude-opus-5" \| "claude-sonnet-4-6" \| "claude-sonnet-5" \| "meta-llama/Llama-3.3-70B-Instruct-Turbo" \| "llama-3.3-70b-versatile" \| "llama-3.1-8b-instant" \| "llama3.3" \| "llama3.2" \| "llama3" \| "llama3.1:405b" \| "dolphin-mistral:latest" \| "openai/gpt-oss-120b" \| "openai/gpt-oss-20b" \| "google/gemini-2.5-pro" \| "google/gemini-3.1-pro-preview" \| "google/gemini-3-flash-preview" \| "google/gemini-2.5-flash" \| "google/gemini-2.0-flash-001" \| "google/gemini-3.1-flash-lite-preview" \| "google/gemini-2.5-flash-lite" \| "google/gemini-2.0-flash-lite-001" \| "mistralai/mistral-large-2512" \| "mistralai/mistral-medium-3.1" \| "mistralai/mistral-small-3.2-24b-instruct" \| "mistralai/codestral-2508" \| "cohere/command-a-03-2025" \| "cohere/command-a-translate-08-2025" \| "cohere/command-a-reasoning-08-2025" \| "cohere/command-a-vision-07-2025" \| "deepseek/deepseek-chat" \| "deepseek/deepseek-r1-0528" \| "perplexity/sonar" \| "perplexity/sonar-pro" \| "perplexity/sonar-reasoning-pro" \| "perplexity/sonar-deep-research" \| "nousresearch/hermes-3-llama-3.1-405b" \| "nousresearch/hermes-3-llama-3.1-70b" \| "amazon/nova-lite-v1" \| "amazon/nova-micro-v1" \| "amazon/nova-pro-v1" \| "microsoft/phi-4" \| "gryphe/mythomax-l2-13b" \| "meta-llama/llama-4-scout" \| "meta-llama/llama-4-maverick" \| "x-ai/grok-3" \| "x-ai/grok-4" \| "x-ai/grok-4-fast" \| "x-ai/grok-4.1-fast" \| "x-ai/grok-4.20" \| "x-ai/grok-4.20-multi-agent" \| "x-ai/grok-code-fast-1" \| "moonshotai/kimi-k2.5" \| "moonshotai/kimi-k2.6" \| "moonshotai/kimi-k2-thinking" \| "moonshotai/kimi-k3" \| "qwen/qwen3-235b-a22b-thinking-2507" \| "qwen/qwen3-coder" \| "z-ai/glm-4.6" \| "z-ai/glm-4.6v" \| "z-ai/glm-4.7" \| "z-ai/glm-4.7-flash" \| "z-ai/glm-5" \| "z-ai/glm-5-turbo" \| "z-ai/glm-5v-turbo" \| "Llama-4-Scout-17B-16E-Instruct-FP8" \| "Llama-4-Maverick-17B-128E-Instruct-FP8" \| "Llama-3.3-8B-Instruct" \| "Llama-3.3-70B-Instruct" \| "v0-1.5-md" \| "v0-1.5-lg" \| "v0-1.0-md" | No |
+| model | The language model to use for answering the prompt. | "o3-mini" \| "o3-2025-04-16" \| "gpt-5.2-2025-12-11" \| "gpt-5.1-2025-11-13" \| "gpt-5-2025-08-07" \| "gpt-5-mini-2025-08-07" \| "o4-mini" \| "o3-pro" \| "o1" \| "o1-mini" \| "gpt-6-astra" \| "gpt-5.6-sol" \| "gpt-5.6-terra" \| "gpt-5.6-luna" \| "gpt-5.5-2026-04-23" \| "gpt-5.5-pro" \| "gpt-5.4-2026-03-05" \| "gpt-5.4-mini-2026-03-17" \| "gpt-5.4-nano-2026-03-17" \| "gpt-5.4-pro" \| "gpt-5.3-chat-latest" \| "gpt-5.3-codex" \| "gpt-5.2-pro" \| "gpt-5.1-codex" \| "gpt-5-pro" \| "gpt-4.1-nano" \| "gpt-5-nano-2025-08-07" \| "gpt-5-chat-latest" \| "gpt-4.1-2025-04-14" \| "gpt-4.1-mini-2025-04-14" \| "gpt-4o-mini" \| "gpt-4o" \| "claude-opus-4-5-20251101" \| "claude-sonnet-4-5-20250929" \| "claude-haiku-4-5-20251001" \| "claude-opus-4-6" \| "claude-opus-4-7" \| "claude-opus-5" \| "claude-sonnet-4-6" \| "claude-sonnet-5" \| "claude-fable-5-1" \| "meta-llama/Llama-3.3-70B-Instruct-Turbo" \| "llama-3.3-70b-versatile" \| "llama-3.1-8b-instant" \| "llama3.3" \| "llama3.2" \| "llama3" \| "llama3.1:405b" \| "dolphin-mistral:latest" \| "openai/gpt-oss-120b" \| "openai/gpt-oss-20b" \| "google/gemini-2.5-pro" \| "google/gemini-3.1-pro-preview" \| "google/gemini-3-flash-preview" \| "google/gemini-2.5-flash" \| "google/gemini-2.0-flash-001" \| "google/gemini-3.1-flash-lite-preview" \| "google/gemini-2.5-flash-lite" \| "google/gemini-2.0-flash-lite-001" \| "mistralai/mistral-large-2512" \| "mistralai/mistral-medium-3.1" \| "mistralai/mistral-small-3.2-24b-instruct" \| "mistralai/codestral-2508" \| "cohere/command-a-03-2025" \| "cohere/command-a-translate-08-2025" \| "cohere/command-a-reasoning-08-2025" \| "cohere/command-a-vision-07-2025" \| "deepseek/deepseek-chat" \| "deepseek/deepseek-r1-0528" \| "perplexity/sonar" \| "perplexity/sonar-pro" \| "perplexity/sonar-reasoning-pro" \| "perplexity/sonar-deep-research" \| "nousresearch/hermes-3-llama-3.1-405b" \| "nousresearch/hermes-3-llama-3.1-70b" \| "amazon/nova-lite-v1" \| "amazon/nova-micro-v1" \| "amazon/nova-pro-v1" \| "microsoft/phi-4" \| "gryphe/mythomax-l2-13b" \| "meta-llama/llama-4-scout" \| "meta-llama/llama-4-maverick" \| "x-ai/grok-3" \| "x-ai/grok-4" \| "x-ai/grok-4-fast" \| "x-ai/grok-4.1-fast" \| "x-ai/grok-4.20" \| "x-ai/grok-4.20-multi-agent" \| "x-ai/grok-code-fast-1" \| "moonshotai/kimi-k2.5" \| "moonshotai/kimi-k2.6" \| "moonshotai/kimi-k2-thinking" \| "moonshotai/kimi-k3" \| "qwen/qwen3-235b-a22b-thinking-2507" \| "qwen/qwen3-coder" \| "z-ai/glm-4.6" \| "z-ai/glm-4.6v" \| "z-ai/glm-4.7" \| "z-ai/glm-4.7-flash" \| "z-ai/glm-5" \| "z-ai/glm-5-turbo" \| "z-ai/glm-5v-turbo" \| "Llama-4-Scout-17B-16E-Instruct-FP8" \| "Llama-4-Maverick-17B-128E-Instruct-FP8" \| "Llama-3.3-8B-Instruct" \| "Llama-3.3-70B-Instruct" \| "v0-1.5-md" \| "v0-1.5-lg" \| "v0-1.0-md" | No |
| force_json_output | Whether to force the LLM to produce a JSON-only response. This can increase the block's reliability, but may also reduce the quality of the response because it prohibits the LLM from reasoning before providing its JSON response. | bool | No |
| sys_prompt | The system prompt to provide additional context to the model. | str | No |
| conversation_history | The conversation history to provide context for the prompt. | List[Dict[str, Any]] | No |
@@ -464,7 +464,7 @@ The block sends the input prompt to a chosen LLM, processes the response, and re
| Input | Description | Type | Required |
|-------|-------------|------|----------|
| prompt | The prompt to send to the language model. You can use any of the {keys} from Prompt Values to fill in the prompt with values from the prompt values dictionary by putting them in curly braces. | str | Yes |
-| model | The language model to use for answering the prompt. | "o3-mini" \| "o3-2025-04-16" \| "gpt-5.2-2025-12-11" \| "gpt-5.1-2025-11-13" \| "gpt-5-2025-08-07" \| "gpt-5-mini-2025-08-07" \| "o4-mini" \| "o3-pro" \| "o1" \| "o1-mini" \| "gpt-6-astra" \| "gpt-5.6-sol" \| "gpt-5.6-terra" \| "gpt-5.6-luna" \| "gpt-5.5-2026-04-23" \| "gpt-5.5-pro" \| "gpt-5.4-2026-03-05" \| "gpt-5.4-mini-2026-03-17" \| "gpt-5.4-nano-2026-03-17" \| "gpt-5.4-pro" \| "gpt-5.3-chat-latest" \| "gpt-5.3-codex" \| "gpt-5.2-pro" \| "gpt-5.1-codex" \| "gpt-5-pro" \| "gpt-4.1-nano" \| "gpt-5-nano-2025-08-07" \| "gpt-5-chat-latest" \| "gpt-4.1-2025-04-14" \| "gpt-4.1-mini-2025-04-14" \| "gpt-4o-mini" \| "gpt-4o" \| "claude-opus-4-5-20251101" \| "claude-sonnet-4-5-20250929" \| "claude-haiku-4-5-20251001" \| "claude-opus-4-6" \| "claude-opus-4-7" \| "claude-opus-5" \| "claude-sonnet-4-6" \| "claude-sonnet-5" \| "meta-llama/Llama-3.3-70B-Instruct-Turbo" \| "llama-3.3-70b-versatile" \| "llama-3.1-8b-instant" \| "llama3.3" \| "llama3.2" \| "llama3" \| "llama3.1:405b" \| "dolphin-mistral:latest" \| "openai/gpt-oss-120b" \| "openai/gpt-oss-20b" \| "google/gemini-2.5-pro" \| "google/gemini-3.1-pro-preview" \| "google/gemini-3-flash-preview" \| "google/gemini-2.5-flash" \| "google/gemini-2.0-flash-001" \| "google/gemini-3.1-flash-lite-preview" \| "google/gemini-2.5-flash-lite" \| "google/gemini-2.0-flash-lite-001" \| "mistralai/mistral-large-2512" \| "mistralai/mistral-medium-3.1" \| "mistralai/mistral-small-3.2-24b-instruct" \| "mistralai/codestral-2508" \| "cohere/command-a-03-2025" \| "cohere/command-a-translate-08-2025" \| "cohere/command-a-reasoning-08-2025" \| "cohere/command-a-vision-07-2025" \| "deepseek/deepseek-chat" \| "deepseek/deepseek-r1-0528" \| "perplexity/sonar" \| "perplexity/sonar-pro" \| "perplexity/sonar-reasoning-pro" \| "perplexity/sonar-deep-research" \| "nousresearch/hermes-3-llama-3.1-405b" \| "nousresearch/hermes-3-llama-3.1-70b" \| "amazon/nova-lite-v1" \| "amazon/nova-micro-v1" \| "amazon/nova-pro-v1" \| "microsoft/phi-4" \| "gryphe/mythomax-l2-13b" \| "meta-llama/llama-4-scout" \| "meta-llama/llama-4-maverick" \| "x-ai/grok-3" \| "x-ai/grok-4" \| "x-ai/grok-4-fast" \| "x-ai/grok-4.1-fast" \| "x-ai/grok-4.20" \| "x-ai/grok-4.20-multi-agent" \| "x-ai/grok-code-fast-1" \| "moonshotai/kimi-k2.5" \| "moonshotai/kimi-k2.6" \| "moonshotai/kimi-k2-thinking" \| "moonshotai/kimi-k3" \| "qwen/qwen3-235b-a22b-thinking-2507" \| "qwen/qwen3-coder" \| "z-ai/glm-4.6" \| "z-ai/glm-4.6v" \| "z-ai/glm-4.7" \| "z-ai/glm-4.7-flash" \| "z-ai/glm-5" \| "z-ai/glm-5-turbo" \| "z-ai/glm-5v-turbo" \| "Llama-4-Scout-17B-16E-Instruct-FP8" \| "Llama-4-Maverick-17B-128E-Instruct-FP8" \| "Llama-3.3-8B-Instruct" \| "Llama-3.3-70B-Instruct" \| "v0-1.5-md" \| "v0-1.5-lg" \| "v0-1.0-md" | No |
+| model | The language model to use for answering the prompt. | "o3-mini" \| "o3-2025-04-16" \| "gpt-5.2-2025-12-11" \| "gpt-5.1-2025-11-13" \| "gpt-5-2025-08-07" \| "gpt-5-mini-2025-08-07" \| "o4-mini" \| "o3-pro" \| "o1" \| "o1-mini" \| "gpt-6-astra" \| "gpt-5.6-sol" \| "gpt-5.6-terra" \| "gpt-5.6-luna" \| "gpt-5.5-2026-04-23" \| "gpt-5.5-pro" \| "gpt-5.4-2026-03-05" \| "gpt-5.4-mini-2026-03-17" \| "gpt-5.4-nano-2026-03-17" \| "gpt-5.4-pro" \| "gpt-5.3-chat-latest" \| "gpt-5.3-codex" \| "gpt-5.2-pro" \| "gpt-5.1-codex" \| "gpt-5-pro" \| "gpt-4.1-nano" \| "gpt-5-nano-2025-08-07" \| "gpt-5-chat-latest" \| "gpt-4.1-2025-04-14" \| "gpt-4.1-mini-2025-04-14" \| "gpt-4o-mini" \| "gpt-4o" \| "claude-opus-4-5-20251101" \| "claude-sonnet-4-5-20250929" \| "claude-haiku-4-5-20251001" \| "claude-opus-4-6" \| "claude-opus-4-7" \| "claude-opus-5" \| "claude-sonnet-4-6" \| "claude-sonnet-5" \| "claude-fable-5-1" \| "meta-llama/Llama-3.3-70B-Instruct-Turbo" \| "llama-3.3-70b-versatile" \| "llama-3.1-8b-instant" \| "llama3.3" \| "llama3.2" \| "llama3" \| "llama3.1:405b" \| "dolphin-mistral:latest" \| "openai/gpt-oss-120b" \| "openai/gpt-oss-20b" \| "google/gemini-2.5-pro" \| "google/gemini-3.1-pro-preview" \| "google/gemini-3-flash-preview" \| "google/gemini-2.5-flash" \| "google/gemini-2.0-flash-001" \| "google/gemini-3.1-flash-lite-preview" \| "google/gemini-2.5-flash-lite" \| "google/gemini-2.0-flash-lite-001" \| "mistralai/mistral-large-2512" \| "mistralai/mistral-medium-3.1" \| "mistralai/mistral-small-3.2-24b-instruct" \| "mistralai/codestral-2508" \| "cohere/command-a-03-2025" \| "cohere/command-a-translate-08-2025" \| "cohere/command-a-reasoning-08-2025" \| "cohere/command-a-vision-07-2025" \| "deepseek/deepseek-chat" \| "deepseek/deepseek-r1-0528" \| "perplexity/sonar" \| "perplexity/sonar-pro" \| "perplexity/sonar-reasoning-pro" \| "perplexity/sonar-deep-research" \| "nousresearch/hermes-3-llama-3.1-405b" \| "nousresearch/hermes-3-llama-3.1-70b" \| "amazon/nova-lite-v1" \| "amazon/nova-micro-v1" \| "amazon/nova-pro-v1" \| "microsoft/phi-4" \| "gryphe/mythomax-l2-13b" \| "meta-llama/llama-4-scout" \| "meta-llama/llama-4-maverick" \| "x-ai/grok-3" \| "x-ai/grok-4" \| "x-ai/grok-4-fast" \| "x-ai/grok-4.1-fast" \| "x-ai/grok-4.20" \| "x-ai/grok-4.20-multi-agent" \| "x-ai/grok-code-fast-1" \| "moonshotai/kimi-k2.5" \| "moonshotai/kimi-k2.6" \| "moonshotai/kimi-k2-thinking" \| "moonshotai/kimi-k3" \| "qwen/qwen3-235b-a22b-thinking-2507" \| "qwen/qwen3-coder" \| "z-ai/glm-4.6" \| "z-ai/glm-4.6v" \| "z-ai/glm-4.7" \| "z-ai/glm-4.7-flash" \| "z-ai/glm-5" \| "z-ai/glm-5-turbo" \| "z-ai/glm-5v-turbo" \| "Llama-4-Scout-17B-16E-Instruct-FP8" \| "Llama-4-Maverick-17B-128E-Instruct-FP8" \| "Llama-3.3-8B-Instruct" \| "Llama-3.3-70B-Instruct" \| "v0-1.5-md" \| "v0-1.5-lg" \| "v0-1.0-md" | No |
| sys_prompt | The system prompt to provide additional context to the model. | str | No |
| retry | Number of times to retry the LLM call if the response does not match the expected format. | int | No |
| prompt_values | Values used to fill in the prompt. The values can be used in the prompt by putting them in a double curly braces, e.g. {{variable_name}}. | Dict[str, str] | No |
@@ -501,7 +501,7 @@ The block splits the input text into smaller chunks, sends each chunk to an LLM
| Input | Description | Type | Required |
|-------|-------------|------|----------|
| text | The text to summarize. | str | Yes |
-| model | The language model to use for summarizing the text. | "o3-mini" \| "o3-2025-04-16" \| "gpt-5.2-2025-12-11" \| "gpt-5.1-2025-11-13" \| "gpt-5-2025-08-07" \| "gpt-5-mini-2025-08-07" \| "o4-mini" \| "o3-pro" \| "o1" \| "o1-mini" \| "gpt-6-astra" \| "gpt-5.6-sol" \| "gpt-5.6-terra" \| "gpt-5.6-luna" \| "gpt-5.5-2026-04-23" \| "gpt-5.5-pro" \| "gpt-5.4-2026-03-05" \| "gpt-5.4-mini-2026-03-17" \| "gpt-5.4-nano-2026-03-17" \| "gpt-5.4-pro" \| "gpt-5.3-chat-latest" \| "gpt-5.3-codex" \| "gpt-5.2-pro" \| "gpt-5.1-codex" \| "gpt-5-pro" \| "gpt-4.1-nano" \| "gpt-5-nano-2025-08-07" \| "gpt-5-chat-latest" \| "gpt-4.1-2025-04-14" \| "gpt-4.1-mini-2025-04-14" \| "gpt-4o-mini" \| "gpt-4o" \| "claude-opus-4-5-20251101" \| "claude-sonnet-4-5-20250929" \| "claude-haiku-4-5-20251001" \| "claude-opus-4-6" \| "claude-opus-4-7" \| "claude-opus-5" \| "claude-sonnet-4-6" \| "claude-sonnet-5" \| "meta-llama/Llama-3.3-70B-Instruct-Turbo" \| "llama-3.3-70b-versatile" \| "llama-3.1-8b-instant" \| "llama3.3" \| "llama3.2" \| "llama3" \| "llama3.1:405b" \| "dolphin-mistral:latest" \| "openai/gpt-oss-120b" \| "openai/gpt-oss-20b" \| "google/gemini-2.5-pro" \| "google/gemini-3.1-pro-preview" \| "google/gemini-3-flash-preview" \| "google/gemini-2.5-flash" \| "google/gemini-2.0-flash-001" \| "google/gemini-3.1-flash-lite-preview" \| "google/gemini-2.5-flash-lite" \| "google/gemini-2.0-flash-lite-001" \| "mistralai/mistral-large-2512" \| "mistralai/mistral-medium-3.1" \| "mistralai/mistral-small-3.2-24b-instruct" \| "mistralai/codestral-2508" \| "cohere/command-a-03-2025" \| "cohere/command-a-translate-08-2025" \| "cohere/command-a-reasoning-08-2025" \| "cohere/command-a-vision-07-2025" \| "deepseek/deepseek-chat" \| "deepseek/deepseek-r1-0528" \| "perplexity/sonar" \| "perplexity/sonar-pro" \| "perplexity/sonar-reasoning-pro" \| "perplexity/sonar-deep-research" \| "nousresearch/hermes-3-llama-3.1-405b" \| "nousresearch/hermes-3-llama-3.1-70b" \| "amazon/nova-lite-v1" \| "amazon/nova-micro-v1" \| "amazon/nova-pro-v1" \| "microsoft/phi-4" \| "gryphe/mythomax-l2-13b" \| "meta-llama/llama-4-scout" \| "meta-llama/llama-4-maverick" \| "x-ai/grok-3" \| "x-ai/grok-4" \| "x-ai/grok-4-fast" \| "x-ai/grok-4.1-fast" \| "x-ai/grok-4.20" \| "x-ai/grok-4.20-multi-agent" \| "x-ai/grok-code-fast-1" \| "moonshotai/kimi-k2.5" \| "moonshotai/kimi-k2.6" \| "moonshotai/kimi-k2-thinking" \| "moonshotai/kimi-k3" \| "qwen/qwen3-235b-a22b-thinking-2507" \| "qwen/qwen3-coder" \| "z-ai/glm-4.6" \| "z-ai/glm-4.6v" \| "z-ai/glm-4.7" \| "z-ai/glm-4.7-flash" \| "z-ai/glm-5" \| "z-ai/glm-5-turbo" \| "z-ai/glm-5v-turbo" \| "Llama-4-Scout-17B-16E-Instruct-FP8" \| "Llama-4-Maverick-17B-128E-Instruct-FP8" \| "Llama-3.3-8B-Instruct" \| "Llama-3.3-70B-Instruct" \| "v0-1.5-md" \| "v0-1.5-lg" \| "v0-1.0-md" | No |
+| model | The language model to use for summarizing the text. | "o3-mini" \| "o3-2025-04-16" \| "gpt-5.2-2025-12-11" \| "gpt-5.1-2025-11-13" \| "gpt-5-2025-08-07" \| "gpt-5-mini-2025-08-07" \| "o4-mini" \| "o3-pro" \| "o1" \| "o1-mini" \| "gpt-6-astra" \| "gpt-5.6-sol" \| "gpt-5.6-terra" \| "gpt-5.6-luna" \| "gpt-5.5-2026-04-23" \| "gpt-5.5-pro" \| "gpt-5.4-2026-03-05" \| "gpt-5.4-mini-2026-03-17" \| "gpt-5.4-nano-2026-03-17" \| "gpt-5.4-pro" \| "gpt-5.3-chat-latest" \| "gpt-5.3-codex" \| "gpt-5.2-pro" \| "gpt-5.1-codex" \| "gpt-5-pro" \| "gpt-4.1-nano" \| "gpt-5-nano-2025-08-07" \| "gpt-5-chat-latest" \| "gpt-4.1-2025-04-14" \| "gpt-4.1-mini-2025-04-14" \| "gpt-4o-mini" \| "gpt-4o" \| "claude-opus-4-5-20251101" \| "claude-sonnet-4-5-20250929" \| "claude-haiku-4-5-20251001" \| "claude-opus-4-6" \| "claude-opus-4-7" \| "claude-opus-5" \| "claude-sonnet-4-6" \| "claude-sonnet-5" \| "claude-fable-5-1" \| "meta-llama/Llama-3.3-70B-Instruct-Turbo" \| "llama-3.3-70b-versatile" \| "llama-3.1-8b-instant" \| "llama3.3" \| "llama3.2" \| "llama3" \| "llama3.1:405b" \| "dolphin-mistral:latest" \| "openai/gpt-oss-120b" \| "openai/gpt-oss-20b" \| "google/gemini-2.5-pro" \| "google/gemini-3.1-pro-preview" \| "google/gemini-3-flash-preview" \| "google/gemini-2.5-flash" \| "google/gemini-2.0-flash-001" \| "google/gemini-3.1-flash-lite-preview" \| "google/gemini-2.5-flash-lite" \| "google/gemini-2.0-flash-lite-001" \| "mistralai/mistral-large-2512" \| "mistralai/mistral-medium-3.1" \| "mistralai/mistral-small-3.2-24b-instruct" \| "mistralai/codestral-2508" \| "cohere/command-a-03-2025" \| "cohere/command-a-translate-08-2025" \| "cohere/command-a-reasoning-08-2025" \| "cohere/command-a-vision-07-2025" \| "deepseek/deepseek-chat" \| "deepseek/deepseek-r1-0528" \| "perplexity/sonar" \| "perplexity/sonar-pro" \| "perplexity/sonar-reasoning-pro" \| "perplexity/sonar-deep-research" \| "nousresearch/hermes-3-llama-3.1-405b" \| "nousresearch/hermes-3-llama-3.1-70b" \| "amazon/nova-lite-v1" \| "amazon/nova-micro-v1" \| "amazon/nova-pro-v1" \| "microsoft/phi-4" \| "gryphe/mythomax-l2-13b" \| "meta-llama/llama-4-scout" \| "meta-llama/llama-4-maverick" \| "x-ai/grok-3" \| "x-ai/grok-4" \| "x-ai/grok-4-fast" \| "x-ai/grok-4.1-fast" \| "x-ai/grok-4.20" \| "x-ai/grok-4.20-multi-agent" \| "x-ai/grok-code-fast-1" \| "moonshotai/kimi-k2.5" \| "moonshotai/kimi-k2.6" \| "moonshotai/kimi-k2-thinking" \| "moonshotai/kimi-k3" \| "qwen/qwen3-235b-a22b-thinking-2507" \| "qwen/qwen3-coder" \| "z-ai/glm-4.6" \| "z-ai/glm-4.6v" \| "z-ai/glm-4.7" \| "z-ai/glm-4.7-flash" \| "z-ai/glm-5" \| "z-ai/glm-5-turbo" \| "z-ai/glm-5v-turbo" \| "Llama-4-Scout-17B-16E-Instruct-FP8" \| "Llama-4-Maverick-17B-128E-Instruct-FP8" \| "Llama-3.3-8B-Instruct" \| "Llama-3.3-70B-Instruct" \| "v0-1.5-md" \| "v0-1.5-lg" \| "v0-1.0-md" | No |
| focus | The topic to focus on in the summary | str | No |
| style | The style of the summary to generate. | "concise" \| "detailed" \| "bullet points" \| "numbered list" | No |
| max_tokens | The maximum number of tokens to generate in the chat completion. | int | No |
@@ -724,7 +724,7 @@ In the default `built_in` execution mode, configure `agent_mode_max_iterations`
| Input | Description | Type | Required |
|-------|-------------|------|----------|
| prompt | The prompt to send to the language model. | str | Yes |
-| model | The language model to use for answering the prompt. | "o3-mini" \| "o3-2025-04-16" \| "gpt-5.2-2025-12-11" \| "gpt-5.1-2025-11-13" \| "gpt-5-2025-08-07" \| "gpt-5-mini-2025-08-07" \| "o4-mini" \| "o3-pro" \| "o1" \| "o1-mini" \| "gpt-6-astra" \| "gpt-5.6-sol" \| "gpt-5.6-terra" \| "gpt-5.6-luna" \| "gpt-5.5-2026-04-23" \| "gpt-5.5-pro" \| "gpt-5.4-2026-03-05" \| "gpt-5.4-mini-2026-03-17" \| "gpt-5.4-nano-2026-03-17" \| "gpt-5.4-pro" \| "gpt-5.3-chat-latest" \| "gpt-5.3-codex" \| "gpt-5.2-pro" \| "gpt-5.1-codex" \| "gpt-5-pro" \| "gpt-4.1-nano" \| "gpt-5-nano-2025-08-07" \| "gpt-5-chat-latest" \| "gpt-4.1-2025-04-14" \| "gpt-4.1-mini-2025-04-14" \| "gpt-4o-mini" \| "gpt-4o" \| "claude-opus-4-5-20251101" \| "claude-sonnet-4-5-20250929" \| "claude-haiku-4-5-20251001" \| "claude-opus-4-6" \| "claude-opus-4-7" \| "claude-opus-5" \| "claude-sonnet-4-6" \| "claude-sonnet-5" \| "meta-llama/Llama-3.3-70B-Instruct-Turbo" \| "llama-3.3-70b-versatile" \| "llama-3.1-8b-instant" \| "llama3.3" \| "llama3.2" \| "llama3" \| "llama3.1:405b" \| "dolphin-mistral:latest" \| "openai/gpt-oss-120b" \| "openai/gpt-oss-20b" \| "google/gemini-2.5-pro" \| "google/gemini-3.1-pro-preview" \| "google/gemini-3-flash-preview" \| "google/gemini-2.5-flash" \| "google/gemini-2.0-flash-001" \| "google/gemini-3.1-flash-lite-preview" \| "google/gemini-2.5-flash-lite" \| "google/gemini-2.0-flash-lite-001" \| "mistralai/mistral-large-2512" \| "mistralai/mistral-medium-3.1" \| "mistralai/mistral-small-3.2-24b-instruct" \| "mistralai/codestral-2508" \| "cohere/command-a-03-2025" \| "cohere/command-a-translate-08-2025" \| "cohere/command-a-reasoning-08-2025" \| "cohere/command-a-vision-07-2025" \| "deepseek/deepseek-chat" \| "deepseek/deepseek-r1-0528" \| "perplexity/sonar" \| "perplexity/sonar-pro" \| "perplexity/sonar-reasoning-pro" \| "perplexity/sonar-deep-research" \| "nousresearch/hermes-3-llama-3.1-405b" \| "nousresearch/hermes-3-llama-3.1-70b" \| "amazon/nova-lite-v1" \| "amazon/nova-micro-v1" \| "amazon/nova-pro-v1" \| "microsoft/phi-4" \| "gryphe/mythomax-l2-13b" \| "meta-llama/llama-4-scout" \| "meta-llama/llama-4-maverick" \| "x-ai/grok-3" \| "x-ai/grok-4" \| "x-ai/grok-4-fast" \| "x-ai/grok-4.1-fast" \| "x-ai/grok-4.20" \| "x-ai/grok-4.20-multi-agent" \| "x-ai/grok-code-fast-1" \| "moonshotai/kimi-k2.5" \| "moonshotai/kimi-k2.6" \| "moonshotai/kimi-k2-thinking" \| "moonshotai/kimi-k3" \| "qwen/qwen3-235b-a22b-thinking-2507" \| "qwen/qwen3-coder" \| "z-ai/glm-4.6" \| "z-ai/glm-4.6v" \| "z-ai/glm-4.7" \| "z-ai/glm-4.7-flash" \| "z-ai/glm-5" \| "z-ai/glm-5-turbo" \| "z-ai/glm-5v-turbo" \| "Llama-4-Scout-17B-16E-Instruct-FP8" \| "Llama-4-Maverick-17B-128E-Instruct-FP8" \| "Llama-3.3-8B-Instruct" \| "Llama-3.3-70B-Instruct" \| "v0-1.5-md" \| "v0-1.5-lg" \| "v0-1.0-md" | No |
+| model | The language model to use for answering the prompt. | "o3-mini" \| "o3-2025-04-16" \| "gpt-5.2-2025-12-11" \| "gpt-5.1-2025-11-13" \| "gpt-5-2025-08-07" \| "gpt-5-mini-2025-08-07" \| "o4-mini" \| "o3-pro" \| "o1" \| "o1-mini" \| "gpt-6-astra" \| "gpt-5.6-sol" \| "gpt-5.6-terra" \| "gpt-5.6-luna" \| "gpt-5.5-2026-04-23" \| "gpt-5.5-pro" \| "gpt-5.4-2026-03-05" \| "gpt-5.4-mini-2026-03-17" \| "gpt-5.4-nano-2026-03-17" \| "gpt-5.4-pro" \| "gpt-5.3-chat-latest" \| "gpt-5.3-codex" \| "gpt-5.2-pro" \| "gpt-5.1-codex" \| "gpt-5-pro" \| "gpt-4.1-nano" \| "gpt-5-nano-2025-08-07" \| "gpt-5-chat-latest" \| "gpt-4.1-2025-04-14" \| "gpt-4.1-mini-2025-04-14" \| "gpt-4o-mini" \| "gpt-4o" \| "claude-opus-4-5-20251101" \| "claude-sonnet-4-5-20250929" \| "claude-haiku-4-5-20251001" \| "claude-opus-4-6" \| "claude-opus-4-7" \| "claude-opus-5" \| "claude-sonnet-4-6" \| "claude-sonnet-5" \| "claude-fable-5-1" \| "meta-llama/Llama-3.3-70B-Instruct-Turbo" \| "llama-3.3-70b-versatile" \| "llama-3.1-8b-instant" \| "llama3.3" \| "llama3.2" \| "llama3" \| "llama3.1:405b" \| "dolphin-mistral:latest" \| "openai/gpt-oss-120b" \| "openai/gpt-oss-20b" \| "google/gemini-2.5-pro" \| "google/gemini-3.1-pro-preview" \| "google/gemini-3-flash-preview" \| "google/gemini-2.5-flash" \| "google/gemini-2.0-flash-001" \| "google/gemini-3.1-flash-lite-preview" \| "google/gemini-2.5-flash-lite" \| "google/gemini-2.0-flash-lite-001" \| "mistralai/mistral-large-2512" \| "mistralai/mistral-medium-3.1" \| "mistralai/mistral-small-3.2-24b-instruct" \| "mistralai/codestral-2508" \| "cohere/command-a-03-2025" \| "cohere/command-a-translate-08-2025" \| "cohere/command-a-reasoning-08-2025" \| "cohere/command-a-vision-07-2025" \| "deepseek/deepseek-chat" \| "deepseek/deepseek-r1-0528" \| "perplexity/sonar" \| "perplexity/sonar-pro" \| "perplexity/sonar-reasoning-pro" \| "perplexity/sonar-deep-research" \| "nousresearch/hermes-3-llama-3.1-405b" \| "nousresearch/hermes-3-llama-3.1-70b" \| "amazon/nova-lite-v1" \| "amazon/nova-micro-v1" \| "amazon/nova-pro-v1" \| "microsoft/phi-4" \| "gryphe/mythomax-l2-13b" \| "meta-llama/llama-4-scout" \| "meta-llama/llama-4-maverick" \| "x-ai/grok-3" \| "x-ai/grok-4" \| "x-ai/grok-4-fast" \| "x-ai/grok-4.1-fast" \| "x-ai/grok-4.20" \| "x-ai/grok-4.20-multi-agent" \| "x-ai/grok-code-fast-1" \| "moonshotai/kimi-k2.5" \| "moonshotai/kimi-k2.6" \| "moonshotai/kimi-k2-thinking" \| "moonshotai/kimi-k3" \| "qwen/qwen3-235b-a22b-thinking-2507" \| "qwen/qwen3-coder" \| "z-ai/glm-4.6" \| "z-ai/glm-4.6v" \| "z-ai/glm-4.7" \| "z-ai/glm-4.7-flash" \| "z-ai/glm-5" \| "z-ai/glm-5-turbo" \| "z-ai/glm-5v-turbo" \| "Llama-4-Scout-17B-16E-Instruct-FP8" \| "Llama-4-Maverick-17B-128E-Instruct-FP8" \| "Llama-3.3-8B-Instruct" \| "Llama-3.3-70B-Instruct" \| "v0-1.5-md" \| "v0-1.5-lg" \| "v0-1.0-md" | No |
| multiple_tool_calls | Whether to allow multiple tool calls in a single response. | bool | No |
| sys_prompt | The system prompt to provide additional context to the model. | str | No |
| conversation_history | The conversation history to provide context for the prompt. | List[Dict[str, Any]] | No |