Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

fix(mcp-store): negotiate the mcp protocol version when syncing tools (#129523)

Jake Ruthe7f2bc2cb246
diff --git a/.claude/rules/mcp-store-parity.md b/.claude/rules/mcp-store-parity.md
index 970e4db8ec88..e67f35084cd7 100644
--- a/.claude/rules/mcp-store-parity.md
+++ b/.claude/rules/mcp-store-parity.md
@@ -1,17 +1,9 @@
---
paths:
- 'products/mcp_store/**'
- - 'products/desktop/packages/ui/src/features/mcp-servers/**'
- - 'products/desktop/packages/ui/src/features/mcp-gateway/**'
- - 'products/desktop/packages/ui/src/features/mcp-server-manager/**'
- 'products/desktop/packages/api-client/src/mcp-gateway.ts'
---
-The MCP store UI is implemented twice against the same backend and feature flags, with no shared UI code:
-the web app (`products/mcp_store/frontend/`, Kea + LemonUI) and PostHog Desktop
-(`products/desktop/packages/ui/src/features/mcp-servers/`, `mcp-gateway/`, `mcp-server-manager/`; TanStack Query + quill).
-The feature set always changes for both apps together: when you change the feature set or UI in one app,
-make the equivalent change in the other, in the same PR or an explicitly linked follow-up.
-Changes to serializers the gateway UI consumes also need the desktop's hand-written type mirrors in
-`products/desktop/packages/api-client/src/mcp-gateway.ts` updated.
-See "Keep the desktop UI in sync" in `products/mcp_store/README.md` for the directory mapping.
+PostHog Desktop is no longer maintained, so MCP store UI changes in the web app (`products/mcp_store/frontend/`) do not need a Desktop counterpart.
+Desktop still builds against this backend in CI.
+When you change a serializer the gateway UI consumes, keep the desktop's hand-written type mirrors in `products/desktop/packages/api-client/src/mcp-gateway.ts` compiling, or the Desktop checks fail.
diff --git a/frontend/snapshots.yml b/frontend/snapshots.yml
index 1026c89478e2..5e73bb27b73c 100644
--- a/frontend/snapshots.yml
+++ b/frontend/snapshots.yml
@@ -14383,9 +14383,9 @@ snapshots:
scenes-app-mcp-analytics-tool-quality-charts--toggle-wraps-below-title--light:
hash: v1.k794b7964.c260d1264a59afc8e03f867b2814ae9b713a4034979750b522939977e222033e.hS_jhj7c_-8UHf5BFTHcnfaewRvEJULaYwC0W8z1v6U
scenes-app-mcp-gateway-server--page--dark:
- hash: v1.k794b7964.181ef8620fa10882b33a2277dd7729a466e6faa6dd5d47fbf5a8bb2d3d90428e.WgP3PJHt3L3hZCpRpi_ZUpa5I2vqj3yZ-pin7RGupNA
+ hash: v1.k794b7964.4f6a2f3d8448bc0ce5ce344cb6107a0e69ceabbd686fe96e69e3f1b4524c03df.tGUbHtcA63-nJY-PkxCEnDFh3hr6J6yB9PRNih8PsnY
scenes-app-mcp-gateway-server--page--light:
- hash: v1.k794b7964.d12187b259fe0e6231d155a107df2a36acd34a9753f5e033fe550810e3670f1e.C5tJ-Tmk7BqN6ybHBrzwXiqIjZjQlyitOeBl0XDCfR8
+ hash: v1.k794b7964.c70c705466ec0bfeeb79666639f342f1c54754c3c89e746c2cae06df010f640e.x3sgZIHI4FH6KVjgVi0YA-UYQOhlAE3v6qwMy8WQhug
scenes-app-mcp-servers-connect-server-modal--catalog-api-key-template--dark:
hash: v1.k794b7964.88b9762624eed0dad1e68107a83d764446614ec109f78047d3cb7932cbf8512c.1zVCJCmQ7XSt2Cw7Yz8Lqv_GPYFPE8PL0k8tHi_b6Lc
scenes-app-mcp-servers-connect-server-modal--catalog-api-key-template--light:
diff --git a/products/desktop/packages/api-client/src/generated.ts b/products/desktop/packages/api-client/src/generated.ts
index ad2491b5fd95..c75032e18696 100644
--- a/products/desktop/packages/api-client/src/generated.ts
+++ b/products/desktop/packages/api-client/src/generated.ts
@@ -12659,6 +12659,10 @@ export namespace Schemas {
export type MCPServerInstallation = {
id: string;
template_id: string | null;
+ /**
+ * ID of the MCP server this connection belongs to. The MCP server page takes this ID, not the connection id. Null for older connections that are not linked to a server yet.
+ */
+ gateway_server_id: string | null;
name: string;
/**
* Deprecated: use icon_domain instead. Lowercase key from the linked template for clients that still render bundled icon assets. Empty if custom install (no template).
diff --git a/products/desktop/packages/core/src/mcp-servers/status.test.ts b/products/desktop/packages/core/src/mcp-servers/status.test.ts
index c2f6b93d1c3f..7cb4b75b8486 100644
--- a/products/desktop/packages/core/src/mcp-servers/status.test.ts
+++ b/products/desktop/packages/core/src/mcp-servers/status.test.ts
@@ -8,6 +8,7 @@ function makeInstallation(
return {
id: "inst-1",
template_id: null,
+ gateway_server_id: null,
name: "Test",
icon_key: "",
icon_domain: "",
diff --git a/products/mcp_store/README.md b/products/mcp_store/README.md
index 0b5ebfcbaa44..318a8adad7fe 100644
--- a/products/mcp_store/README.md
+++ b/products/mcp_store/README.md
@@ -9,22 +9,11 @@ Tool names missing from the cached registry are re-listed before use and refused
This is unrelated to `products/*/mcp/tools.yaml`, which exposes PostHog's own endpoints as MCP tools.
-## Keep the desktop UI in sync
+## PostHog Desktop
-PostHog Desktop ships its own, independently written frontend for this product — same backend, same feature flags, no shared UI code:
-
-| This product (web app) | PostHog Desktop equivalent |
-| ----------------------------------------------------- | --------------------------------------------------------------- |
-| `frontend/scene/` (marketplace) | `products/desktop/packages/ui/src/features/mcp-servers/` |
-| `frontend/gateway/` + `frontend/settings/` (gateway) | `products/desktop/packages/ui/src/features/mcp-gateway/` |
-| `frontend/scene/AddCustomServerForm.tsx` (custom add) | `products/desktop/packages/ui/src/features/mcp-server-manager/` |
-
-The implementations are parallel, not shared: web uses Kea + LemonUI, desktop uses TanStack Query + quill.
-The desktop also hand-writes its gateway API types in `products/desktop/packages/api-client/src/mcp-gateway.ts` as mirrors of the serializers in `backend/presentation/gateway_views.py`.
-
-The MCP store feature set always changes for both apps together.
-When you change the frontend here — a new workflow, control, state, or flag gate — make the equivalent change in the desktop features above in the same PR, or open an explicitly linked follow-up.
-When you change a serializer the gateway UI consumes, update the desktop's hand-written mirrors too.
+PostHog Desktop is no longer maintained, so web app changes here do not need a Desktop counterpart.
+Desktop still builds against this backend in CI: it hand-writes its gateway API types in `products/desktop/packages/api-client/src/mcp-gateway.ts` as mirrors of the serializers in `backend/presentation/gateway_views.py`.
+When you change a serializer the gateway UI consumes, keep those mirrors compiling.
## Settings experience and rollout
diff --git a/products/mcp_store/backend/catalog.py b/products/mcp_store/backend/catalog.py
index 17c4bbbd5e66..4c221906051c 100644
--- a/products/mcp_store/backend/catalog.py
+++ b/products/mcp_store/backend/catalog.py
@@ -159,6 +159,8 @@ MCP_SERVER_CATALOG: list[CatalogEntry] = [
auth_type="oauth",
category="dev",
icon_domain="firetiger.com",
+ # As of November 2026, the MCP host does not resolve in DNS, so no install can reach the server.
+ disabled=True,
),
CatalogEntry(
name="GitLab",
diff --git a/products/mcp_store/backend/presentation/views.py b/products/mcp_store/backend/presentation/views.py
index 63311aae687b..8e6944a2ac4d 100644
--- a/products/mcp_store/backend/presentation/views.py
+++ b/products/mcp_store/backend/presentation/views.py
@@ -300,6 +300,12 @@ class MCPServerViewSet(TeamAndOrgViewSetMixin, mixins.ListModelMixin, viewsets.G
class MCPServerInstallationSerializer(serializers.ModelSerializer):
template_id = serializers.UUIDField(source="template.id", read_only=True, allow_null=True, default=None)
+ gateway_server_id = serializers.UUIDField(
+ read_only=True,
+ allow_null=True,
+ help_text="ID of the MCP server this connection belongs to. The MCP server page takes this ID, "
+ "not the connection id. Null for older connections that are not linked to a server yet.",
+ )
needs_reauth = serializers.SerializerMethodField()
pending_oauth = serializers.SerializerMethodField()
name = serializers.SerializerMethodField()
@@ -334,6 +340,7 @@ class MCPServerInstallationSerializer(serializers.ModelSerializer):
fields = [
"id",
"template_id",
+ "gateway_server_id",
"name",
"icon_key",
"icon_domain",
@@ -351,7 +358,16 @@ class MCPServerInstallationSerializer(serializers.ModelSerializer):
"created_at",
"updated_at",
]
- read_only_fields = ["id", "template_id", "created_at", "updated_at", "tool_count", "scope", "is_owner"]
+ read_only_fields = [
+ "id",
+ "template_id",
+ "gateway_server_id",
+ "created_at",
+ "updated_at",
+ "tool_count",
+ "scope",
+ "is_owner",
+ ]
def get_tool_count(self, obj: MCPServerInstallation) -> int:
# Prefer the annotation to avoid N+1 on list; fall back to a direct
diff --git a/products/mcp_store/backend/probe.py b/products/mcp_store/backend/probe.py
index 70911aa7f4bf..11b7ec231fbf 100644
--- a/products/mcp_store/backend/probe.py
+++ b/products/mcp_store/backend/probe.py
@@ -33,10 +33,10 @@ from .oauth import (
register_dcr_client,
requested_oauth_scopes,
)
+from .protocol_versions import LATEST_PROTOCOL_VERSION
logger = structlog.get_logger(__name__)
-MCP_PROTOCOL_VERSION = "2025-06-18"
MAX_AUTHORIZE_REDIRECTS = 3
_AUTH_REQUIRED_STATUSES = (401, 403)
@@ -153,7 +153,7 @@ def _probe_initialize(url: str, result: ProbeResult) -> _InitializeOutcome:
"id": 1,
"method": "initialize",
"params": {
- "protocolVersion": MCP_PROTOCOL_VERSION,
+ "protocolVersion": LATEST_PROTOCOL_VERSION,
"capabilities": {},
"clientInfo": {"name": "posthog-mcp-store-probe", "version": "1.0"},
},
diff --git a/products/mcp_store/backend/protocol_versions.py b/products/mcp_store/backend/protocol_versions.py
new file mode 100644
index 000000000000..b356478ad6c3
--- /dev/null
+++ b/products/mcp_store/backend/protocol_versions.py
@@ -0,0 +1,6 @@
+# MCP protocol versions the store's client offers to upstream servers, newest first.
+# 2025-11-25 is left out because it lets a server drop an SSE response stream and expect
+# the client to resume it with a GET request, which this client does not do.
+SUPPORTED_PROTOCOL_VERSIONS: tuple[str, ...] = ("2025-06-18", "2025-03-26", "2024-11-05")
+
+LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0]
diff --git a/products/mcp_store/backend/tasks/tasks.py b/products/mcp_store/backend/tasks/tasks.py
index 5dad7d6b57f2..66352a1bedd5 100644
--- a/products/mcp_store/backend/tasks/tasks.py
+++ b/products/mcp_store/backend/tasks/tasks.py
@@ -1,6 +1,11 @@
+from typing import Any
+from urllib.parse import urlparse
+
import structlog
-from celery import shared_task
+from celery import Task, shared_task
+from posthog.event_usage import groups
+from posthog.ph_client import ph_scoped_capture
from posthog.redis import get_client
from posthog.scoping_audit import skip_team_scope_audit
@@ -46,6 +51,7 @@ def queue_sync_mcp_server_templates() -> None:
# A listing that fails here leaves the installation with no tool rows, and the
# gateway refuses every call to a tool that has no row.
@shared_task(
+ bind=True,
ignore_result=True,
autoretry_for=(ToolsFetchError,),
retry_backoff=30,
@@ -54,10 +60,44 @@ def queue_sync_mcp_server_templates() -> None:
max_retries=5,
)
@skip_team_scope_audit
-def sync_installation_tools_task(installation_id: str) -> None:
+def sync_installation_tools_task(self: Task, installation_id: str) -> None:
try:
installation = MCPServerInstallation.objects.get(id=installation_id)
except MCPServerInstallation.DoesNotExist:
logger.info("sync_installation_tools_task: installation gone", installation_id=installation_id)
return
- sync_installation_tools(installation)
+ try:
+ upstream = sync_installation_tools(installation)
+ except ToolsFetchError:
+ capture_tools_sync_outcome(
+ installation,
+ "mcp_store tools sync failed",
+ {
+ "attempt": self.request.retries + 1,
+ "will_retry": self.request.retries < (self.max_retries or 0),
+ },
+ )
+ raise
+ capture_tools_sync_outcome(
+ installation,
+ "mcp_store tools synced",
+ {"tool_count": len(upstream.tools), "protocol_version": upstream.protocol_version},
+ )
+
+
+def capture_tools_sync_outcome(installation: MCPServerInstallation, event: str, properties: dict[str, Any]) -> None:
+ template = installation.template
+ with ph_scoped_capture() as capture:
+ capture(
+ distinct_id=installation.user.distinct_id or str(installation.team.uuid),
+ event=event,
+ properties={
+ "server_name": template.name if template else installation.display_name,
+ "template_id": str(template.id) if template else None,
+ "server_host": urlparse(installation.url).hostname,
+ "auth_type": installation.auth_type,
+ "installation_id": str(installation.id),
+ **properties,
+ },
+ groups=groups(team=installation.team),
+ )
diff --git a/products/mcp_store/backend/test/test_facade.py b/products/mcp_store/backend/test/test_facade.py
index b8c7565d7f7a..6a58b1a03bb7 100644
--- a/products/mcp_store/backend/test/test_facade.py
+++ b/products/mcp_store/backend/test/test_facade.py
@@ -37,6 +37,7 @@ from products.mcp_store.backend.models import (
MCPServiceAccount,
MCPServiceAccountServerAccess,
)
+from products.mcp_store.backend.tools import UpstreamToolList
class TestGetActiveInstallations(BaseTest):
@@ -1020,7 +1021,9 @@ class TestCallMemberServerTool(BaseTest):
# A connection whose connect-time listing never landed holds no rows, and
# without a re-listing it refuses every call for the life of the connection.
self._installation()
- mock_fetch.return_value = [{"name": "list_events", "annotations": {"readOnlyHint": True}}]
+ mock_fetch.return_value = UpstreamToolList(
+ tools=[{"name": "list_events", "annotations": {"readOnlyHint": True}}]
+ )
# Freshly listed tools are opt-in, so policy answers the call now.
assert self._call().status == "needs_approval"
@@ -1031,7 +1034,9 @@ class TestCallMemberServerTool(BaseTest):
def test_a_removed_tool_the_server_brought_back_is_callable_again(self, mock_call, mock_fetch) -> None:
installation = self._installation()
self._tool(installation, removed_at=timezone.now())
- mock_fetch.return_value = [{"name": "list_events", "annotations": {"readOnlyHint": True}}]
+ mock_fetch.return_value = UpstreamToolList(
+ tools=[{"name": "list_events", "annotations": {"readOnlyHint": True}}]
+ )
assert self._call().status == "ok"
mock_call.assert_called_once()
@@ -1136,7 +1141,7 @@ class TestCallMemberServerTool(BaseTest):
@parameterized.expand(
[("disabled", "do_not_use", None, "blocked"), ("removed", "needs_approval", "removed", "tool_missing")]
)
- @patch("products.mcp_store.backend.tools.fetch_upstream_tools", return_value=[])
+ @patch("products.mcp_store.backend.tools.fetch_upstream_tools", return_value=UpstreamToolList(tools=[]))
@patch("products.mcp_store.backend.facade.api.call_upstream_tool")
def test_approval_does_not_override_blocks(
self,
diff --git a/products/mcp_store/backend/test/test_proxy.py b/products/mcp_store/backend/test/test_proxy.py
index c7756a13229d..30ca4b83adb8 100644
--- a/products/mcp_store/backend/test/test_proxy.py
+++ b/products/mcp_store/backend/test/test_proxy.py
@@ -32,6 +32,7 @@ from products.mcp_store.backend.proxy import (
build_upstream_auth_headers,
validate_installation_auth,
)
+from products.mcp_store.backend.tools import UpstreamToolList
ALLOWED_VERDICT = PinnedUrlVerdict(allowed=True, reason=None, pinned_ips=set())
@@ -754,7 +755,7 @@ class TestMCPProxyToolApproval(ClickhouseTestMixin, APIBaseTest, QueryMatchingTe
assert body["error"]["code"] == -32002
mock_client_cls.assert_not_called()
- @patch("products.mcp_store.backend.tools.fetch_upstream_tools", return_value=[])
+ @patch("products.mcp_store.backend.tools.fetch_upstream_tools", return_value=UpstreamToolList(tools=[]))
@patch("products.mcp_store.backend.proxy.pinned_client")
def test_unknown_tool_returns_method_not_found(self, mock_client_cls, mock_fetch):
installation = self._installation()
@@ -776,7 +777,7 @@ class TestMCPProxyToolApproval(ClickhouseTestMixin, APIBaseTest, QueryMatchingTe
# An installation whose connect-time listing never landed has no rows, and
# without a re-listing it refuses every call for the life of the connection.
installation = self._installation()
- mock_fetch.return_value = [{"name": "search", "description": "Search"}]
+ mock_fetch.return_value = UpstreamToolList(tools=[{"name": "search", "description": "Search"}])
response = self.client.post(
self._proxy_url(installation.id),
@@ -804,7 +805,7 @@ class TestMCPProxyToolApproval(ClickhouseTestMixin, APIBaseTest, QueryMatchingTe
):
installation = self._installation()
self._tool(installation, "legacy", "needs_approval", removed_at=timezone.now())
- mock_fetch.return_value = upstream_tools
+ mock_fetch.return_value = UpstreamToolList(tools=upstream_tools)
response = self.client.post(
self._proxy_url(installation.id),
diff --git a/products/mcp_store/backend/test/test_tools.py b/products/mcp_store/backend/test/test_tools.py
index bbf975402e2b..9d1499530396 100644
--- a/products/mcp_store/backend/test/test_tools.py
+++ b/products/mcp_store/backend/test/test_tools.py
@@ -13,6 +13,7 @@ from django.test import SimpleTestCase, override_settings
from django.utils import timezone
import httpx
+from celery.exceptions import Retry
from parameterized import parameterized
from posthog.redis import get_client
@@ -20,12 +21,14 @@ from posthog.security.url_validation import PinnedUrlVerdict
from products.mcp_store.backend.models import MCPServerInstallation, MCPServerInstallationTool
from products.mcp_store.backend.oauth import discover_oauth_metadata
+from products.mcp_store.backend.tasks.tasks import sync_installation_tools_task
from products.mcp_store.backend.tools import (
CALL_TIMEOUT,
HANDSHAKE_TIMEOUT,
RESYNC_FAILURE_THROTTLE_SECONDS,
ToolCallError,
ToolsFetchError,
+ UpstreamToolList,
call_upstream_tool,
fetch_upstream_tools,
resync_installation_tools,
@@ -226,7 +229,7 @@ class TestFetchUpstreamTools(ClickhouseTestMixin, APIBaseTest):
)
client = _install_handshake_mock(mock_client_cls, tools_list_response=_build_response(body=tools_body))
- tools = fetch_upstream_tools(installation)
+ tools = fetch_upstream_tools(installation).tools
assert [t["name"] for t in tools] == ["alpha", "beta"]
# Verify the handshake order and that the session id rode along on later calls.
@@ -266,7 +269,7 @@ class TestFetchUpstreamTools(ClickhouseTestMixin, APIBaseTest):
client.delete.return_value = _build_response(status=200, body="")
mock_client_cls.return_value.__enter__.return_value = client
- tools = fetch_upstream_tools(installation)
+ tools = fetch_upstream_tools(installation).tools
assert [tool["name"] for tool in tools] == ["alpha"]
assert client.post.call_args_list[0].args[0] == "https://mcp.example.com/mcp"
@@ -287,7 +290,7 @@ class TestFetchUpstreamTools(ClickhouseTestMixin, APIBaseTest):
tools_list_response=_build_response(body=sse_body, content_type="text/event-stream"),
)
- tools = fetch_upstream_tools(installation)
+ tools = fetch_upstream_tools(installation).tools
assert [t["name"] for t in tools] == ["alpha"]
@patch("products.mcp_store.backend.url_policy.validate_url_and_pin_ips", return_value=ALLOWED_VERDICT)
@@ -309,7 +312,7 @@ class TestFetchUpstreamTools(ClickhouseTestMixin, APIBaseTest):
notify_resp = _build_response(status=202, body="")
client.post.side_effect = [init_resp, notify_resp, _build_response(body=tools_body)]
- tools = fetch_upstream_tools(installation)
+ tools = fetch_upstream_tools(installation).tools
assert [t["name"] for t in tools] == ["alpha"]
assert not client.delete.called
@@ -375,7 +378,7 @@ class TestFetchUpstreamTools(ClickhouseTestMixin, APIBaseTest):
call_upstream_tool(installation, "alpha", {})
assert seen == []
return
- tools = fetch_upstream_tools(installation)
+ tools = fetch_upstream_tools(installation).tools
assert [tool["name"] for tool in tools] == ["alpha"]
assert len(seen) == 4
@@ -425,16 +428,83 @@ class TestFetchUpstreamTools(ClickhouseTestMixin, APIBaseTest):
with pytest.raises(ToolsFetchError, match="handshake failed"):
fetch_upstream_tools(installation)
+ @parameterized.expand(
+ [
+ ("answers_the_offer", [{"protocolVersion": "2025-06-18"}], ["2025-06-18"], "2025-06-18"),
+ ("answers_an_older_version", [{"protocolVersion": "2025-03-26"}], ["2025-06-18"], "2025-03-26"),
+ ("rejects_with_400", [400, {"protocolVersion": "2025-03-26"}], ["2025-06-18", "2025-03-26"], "2025-03-26"),
+ (
+ "rejects_with_jsonrpc_error",
+ ["error", "error", {"protocolVersion": "2024-11-05"}],
+ ["2025-06-18", "2025-03-26", "2024-11-05"],
+ "2024-11-05",
+ ),
+ ("answers_an_unknown_version", [{"protocolVersion": "2099-01-01"}], ["2025-06-18"], None),
+ ]
+ )
@patch("products.mcp_store.backend.url_policy.validate_url_and_pin_ips", return_value=ALLOWED_VERDICT)
@patch("products.mcp_store.backend.tools.pinned_client")
- def test_fetch_upstream_tools_raises_on_initialize_error(self, mock_client_cls, _allow):
+ def test_fetch_upstream_tools_negotiates_the_protocol_version(
+ self,
+ _name: str,
+ initialize_replies: list,
+ expected_offers: list[str],
+ expected_header: str | None,
+ mock_client_cls: MagicMock,
+ _allow: MagicMock,
+ ) -> None:
installation = self._installation()
+ initialize_responses = []
+ for reply in initialize_replies:
+ if reply == 400:
+ initialize_responses.append(_build_response(status=400, body="Unsupported protocol version"))
+ elif reply == "error":
+ error = {"code": -32602, "message": "Unsupported protocol version"}
+ initialize_responses.append(
+ _build_response(body=json.dumps({"jsonrpc": "2.0", "id": 1, "error": error}))
+ )
+ else:
+ body = json.dumps({"jsonrpc": "2.0", "id": 1, "result": reply})
+ initialize_responses.append(_build_response(body=body, session_id="sess-1"))
+ tools_body = json.dumps({"jsonrpc": "2.0", "id": 2, "result": {"tools": [{"name": "alpha"}]}})
client = MagicMock()
- client.post.return_value = _build_response(status=401, body="Unauthorized")
+ client.post.side_effect = [
+ *initialize_responses,
+ _build_response(status=202, body=""),
+ _build_response(body=tools_body),
+ ]
+ client.delete.return_value = _build_response(status=200, body="")
mock_client_cls.return_value.__enter__.return_value = client
- with pytest.raises(ToolsFetchError, match="initialize returned status 401"):
+ listing = fetch_upstream_tools(installation)
+
+ assert [tool["name"] for tool in listing.tools] == ["alpha"]
+ assert listing.protocol_version == expected_header
+ *initialize_calls, notify_call, list_call = client.post.call_args_list
+ offers = [json.loads(call.kwargs["content"])["params"]["protocolVersion"] for call in initialize_calls]
+ assert offers == expected_offers
+ assert all("MCP-Protocol-Version" not in call.kwargs["headers"] for call in initialize_calls)
+ for headers in (
+ notify_call.kwargs["headers"],
+ list_call.kwargs["headers"],
+ client.delete.call_args.kwargs["headers"],
+ ):
+ assert headers.get("MCP-Protocol-Version") == expected_header
+
+ @parameterized.expand([("auth_failure_stops", 401, 1), ("every_version_rejected", 400, 3)])
+ @patch("products.mcp_store.backend.url_policy.validate_url_and_pin_ips", return_value=ALLOWED_VERDICT)
+ @patch("products.mcp_store.backend.tools.pinned_client")
+ def test_fetch_upstream_tools_raises_on_initialize_error(
+ self, _name: str, status: int, expected_attempts: int, mock_client_cls: MagicMock, _allow: MagicMock
+ ) -> None:
+ installation = self._installation()
+ client = MagicMock()
+ client.post.return_value = _build_response(status=status, body="rejected")
+ mock_client_cls.return_value.__enter__.return_value = client
+
+ with pytest.raises(ToolsFetchError, match=f"initialize returned status {status}"):
fetch_upstream_tools(installation)
+ assert client.post.call_count == expected_attempts
@patch("products.mcp_store.backend.url_policy.validate_url_and_pin_ips", return_value=ALLOWED_VERDICT)
@patch("products.mcp_store.backend.tools.pinned_client")
@@ -447,7 +517,7 @@ class TestFetchUpstreamTools(ClickhouseTestMixin, APIBaseTest):
)
_install_handshake_mock(mock_client_cls, tools_list_response=_build_response(body=tools_body))
- assert [tool["name"] for tool in fetch_upstream_tools(installation)] == ["alpha"]
+ assert [tool["name"] for tool in fetch_upstream_tools(installation).tools] == ["alpha"]
@patch("products.mcp_store.backend.url_policy.validate_url_and_pin_ips", return_value=ALLOWED_VERDICT)
@patch("products.mcp_store.backend.tools.pinned_client")
@@ -584,7 +654,7 @@ class TestSyncInstallationTools(ClickhouseTestMixin, APIBaseTest):
@patch("products.mcp_store.backend.tools.fetch_upstream_tools")
def test_new_tools_default_to_needs_approval(self, mock_fetch):
installation = self._installation()
- mock_fetch.return_value = [{"name": "search", "description": "Search something"}]
+ mock_fetch.return_value = UpstreamToolList(tools=[{"name": "search", "description": "Search something"}])
sync_installation_tools(installation)
tool = installation.tools.get(tool_name="search")
@@ -598,7 +668,7 @@ class TestSyncInstallationTools(ClickhouseTestMixin, APIBaseTest):
# and the loser of the (installation, tool_name) unique constraint would
# raise — a 500 out of the proxy, since nothing catches IntegrityError.
installation = self._installation()
- mock_fetch.return_value = [{"name": "search", "description": "fresh"}]
+ mock_fetch.return_value = UpstreamToolList(tools=[{"name": "search", "description": "fresh"}])
def create_the_row_behind_this_sync(_installation):
MCPServerInstallationTool.objects.create(
@@ -621,25 +691,27 @@ class TestSyncInstallationTools(ClickhouseTestMixin, APIBaseTest):
@patch("products.mcp_store.backend.tools.fetch_upstream_tools")
def test_sync_persists_upstream_annotations(self, mock_fetch):
installation = self._installation()
- mock_fetch.return_value = [{"name": "search", "annotations": {"destructiveHint": True}}]
+ mock_fetch.return_value = UpstreamToolList(tools=[{"name": "search", "annotations": {"destructiveHint": True}}])
sync_installation_tools(installation)
assert installation.tools.get(tool_name="search").annotations == {"destructiveHint": True}
- mock_fetch.return_value = [{"name": "search", "annotations": {"destructiveHint": False}}]
+ mock_fetch.return_value = UpstreamToolList(
+ tools=[{"name": "search", "annotations": {"destructiveHint": False}}]
+ )
sync_installation_tools(installation)
assert installation.tools.get(tool_name="search").annotations == {"destructiveHint": False}
@patch("products.mcp_store.backend.tools.fetch_upstream_tools")
def test_disappeared_tool_marked_removed_state_preserved(self, mock_fetch):
installation = self._installation()
- mock_fetch.return_value = [{"name": "search"}]
+ mock_fetch.return_value = UpstreamToolList(tools=[{"name": "search"}])
sync_installation_tools(installation)
tool = installation.tools.get(tool_name="search")
tool.approval_state = "approved"
tool.save(update_fields=["approval_state"])
- mock_fetch.return_value = [] # upstream dropped the tool
+ mock_fetch.return_value = UpstreamToolList(tools=[]) # upstream dropped the tool
sync_installation_tools(installation)
tool.refresh_from_db()
assert tool.removed_at is not None
@@ -659,7 +731,7 @@ class TestSyncInstallationTools(ClickhouseTestMixin, APIBaseTest):
removed_at=timezone.now(),
)
- mock_fetch.return_value = [{"name": "write", "description": "updated"}]
+ mock_fetch.return_value = UpstreamToolList(tools=[{"name": "write", "description": "updated"}])
sync_installation_tools(installation)
tool = installation.tools.get(tool_name="write")
@@ -680,13 +752,15 @@ class TestSyncInstallationTools(ClickhouseTestMixin, APIBaseTest):
last_seen_at=timezone.now(),
)
- mock_fetch.return_value = [
- {
- "name": "search",
- "description": "new description",
- "inputSchema": {"type": "object", "properties": {"query": {"type": "string"}}},
- }
- ]
+ mock_fetch.return_value = UpstreamToolList(
+ tools=[
+ {
+ "name": "search",
+ "description": "new description",
+ "inputSchema": {"type": "object", "properties": {"query": {"type": "string"}}},
+ }
+ ]
+ )
sync_installation_tools(installation)
tool = installation.tools.get(tool_name="search")
@@ -711,7 +785,7 @@ class TestResyncInstallationTools(ClickhouseTestMixin, APIBaseTest):
# Callers re-list on a miss, so without the throttle an agent looping on a
# name the server does not have opens one handshake per call.
installation = self._installation()
- mock_fetch.return_value = [{"name": "search"}]
+ mock_fetch.return_value = UpstreamToolList(tools=[{"name": "search"}])
assert resync_installation_tools(installation) is True
assert resync_installation_tools(installation) is False
@@ -730,3 +804,66 @@ class TestResyncInstallationTools(ClickhouseTestMixin, APIBaseTest):
# keep both repair paths shut long after a transient fault cleared.
remaining = get_client().ttl(f"mcp_store:tools_resync:{installation.id}")
assert 0 < remaining <= RESYNC_FAILURE_THROTTLE_SECONDS
+
+
+class TestSyncInstallationToolsTask(ClickhouseTestMixin, APIBaseTest):
+ @parameterized.expand(
+ [
+ ("synced", None, 0, "mcp_store tools synced", {"tool_count": 2, "protocol_version": "2025-06-18"}),
+ (
+ "failed_first_attempt",
+ Retry,
+ 0,
+ "mcp_store tools sync failed",
+ {"attempt": 1, "will_retry": True},
+ ),
+ (
+ "failed_last_attempt",
+ ToolsFetchError,
+ 5,
+ "mcp_store tools sync failed",
+ {"attempt": 6, "will_retry": False},
+ ),
+ ]
+ )
+ @patch("products.mcp_store.backend.tools.fetch_upstream_tools")
+ def test_reports_the_sync_outcome(
+ self,
+ _name: str,
+ raised: type[Exception] | None,
+ retries: int,
+ expected_event: str,
+ expected_properties: dict,
+ mock_fetch: MagicMock,
+ ) -> None:
+ installation = MCPServerInstallation.objects.create(
+ team=self.team,
+ user=self.user,
+ url="https://mcp.example.com/mcp",
+ display_name="Test",
+ auth_type="api_key",
+ sensitive_configuration={"api_key": "sk-test"},
+ )
+ if raised is None:
+ mock_fetch.return_value = UpstreamToolList(
+ tools=[{"name": "search"}, {"name": "fetch"}], protocol_version="2025-06-18"
+ )
+ else:
+ mock_fetch.side_effect = ToolsFetchError("Upstream initialize returned status 400")
+ capture = MagicMock()
+ scoped_capture = MagicMock()
+ scoped_capture.return_value.__enter__.return_value = capture
+
+ with patch("products.mcp_store.backend.tasks.tasks.ph_scoped_capture", scoped_capture):
+ if raised is None:
+ sync_installation_tools_task.apply(args=[str(installation.id)], retries=retries)
+ else:
+ with pytest.raises(raised):
+ sync_installation_tools_task.apply(args=[str(installation.id)], retries=retries)
+
+ capture.assert_called_once()
+ event = capture.call_args.kwargs
+ assert event["event"] == expected_event
+ assert event["distinct_id"] == self.user.distinct_id
+ assert event["properties"]["server_host"] == "mcp.example.com"
+ assert expected_properties.items() <= event["properties"].items()
diff --git a/products/mcp_store/backend/tools.py b/products/mcp_store/backend/tools.py
index 1c5deb8f8d8b..ba4729a2c2c5 100644
--- a/products/mcp_store/backend/tools.py
+++ b/products/mcp_store/backend/tools.py
@@ -8,12 +8,14 @@ through `resync_installation_tools` when a caller names a tool that has no row.
import json
from typing import Any
+from urllib.parse import urlparse
from django.utils import timezone
import httpx
import structlog
+from posthog.dataclasses import frozen
from posthog.redis import get_client
from posthog.security.pinned_httpx import pinned_client
from posthog.security.pinned_requests import SSRFBlockedError
@@ -22,6 +24,7 @@ from .models import MCPServerInstallation, MCPServerInstallationTool
from .oauth import TokenRefreshError, is_token_expiring, refresh_installation_token
from .oauth_credentials import oauth_credentials_source_is_allowed
from .policy import SYNC_DEFAULT_APPROVAL_STATE
+from .protocol_versions import SUPPORTED_PROTOCOL_VERSIONS
from .proxy import build_upstream_auth_headers, validated_same_origin_redirect_url
from .url_policy import resolve_mcp_url_policy, trust_environment_proxy
@@ -33,10 +36,6 @@ _INITIALIZE_ID = 1
_TOOLS_LIST_ID = 2
_TOOLS_CALL_ID = 3
-# MCP protocol version we claim to speak. Kept in sync with what the PostHog
-# MCP reference client sends; bump when the spec changes in a backwards-
-# incompatible way.
-_PROTOCOL_VERSION = "2024-11-05"
_CLIENT_INFO: dict[str, Any] = {"name": "posthog-mcp-store", "version": "1.0"}
# Each handshake step should return in well under a second.
@@ -68,6 +67,32 @@ class ToolsFetchError(Exception):
pass
+class _OfferRejected(ToolsFetchError):
+ """The server refused ``initialize`` outright, so an older protocol version may still work."""
+
+
+@frozen
+class _UpstreamSession:
+ session_id: str | None
+ url: str
+ # None when the server answered with a version outside SUPPORTED_PROTOCOL_VERSIONS.
+ protocol_version: str | None
+
+ def headers(self, base_headers: dict[str, str]) -> dict[str, str]:
+ headers = dict(base_headers)
+ if self.session_id:
+ headers["Mcp-Session-Id"] = self.session_id
+ if self.protocol_version:
+ headers["MCP-Protocol-Version"] = self.protocol_version
+ return headers
+
+
+@frozen
+class UpstreamToolList:
+ tools: list[dict[str, Any]]
+ protocol_version: str | None = None
+
+
class ToolCallError(Exception):
"""An upstream ``tools/call`` failed. Distinct from ToolsFetchError so
callers can tell "we couldn't discover tools" from "the call itself
@@ -90,7 +115,7 @@ def _ensure_valid_token_for_fetch(installation: MCPServerInstallation) -> None:
raise ToolsFetchError(f"Token refresh failed: {exc}") from exc
-def fetch_upstream_tools(installation: MCPServerInstallation) -> list[dict[str, Any]]:
+def fetch_upstream_tools(installation: MCPServerInstallation) -> UpstreamToolList:
"""Send a JSON-RPC ``tools/list`` to the upstream MCP server and return its tool array.
Follows the MCP streamable HTTP handshake: ``initialize`` → ``notifications/initialized``
@@ -125,19 +150,20 @@ def fetch_upstream_tools(installation: MCPServerInstallation) -> list[dict[str,
max_response_bytes=MAX_RESPONSE_BYTES,
trust_env=trust_environment_proxy(installation.url, installation.team_id),
) as client:
- session_id, upstream_url = _mcp_initialize(client, installation.url, base_headers)
- session_headers = dict(base_headers)
- if session_id:
- session_headers["Mcp-Session-Id"] = session_id
+ session = _mcp_initialize(client, installation.url, base_headers)
+ session_headers = session.headers(base_headers)
- _mcp_send_initialized(client, upstream_url, session_headers)
+ _mcp_send_initialized(client, session.url, session_headers)
try:
- return _mcp_list_tools(client, upstream_url, session_headers)
+ return UpstreamToolList(
+ tools=_mcp_list_tools(client, session.url, session_headers),
+ protocol_version=session.protocol_version,
+ )
finally:
# Best-effort cleanup so we don't leak sessions upstream. Failures
# here are purely janitorial and must not mask real errors above.
- if session_id:
- _mcp_terminate_session(client, upstream_url, session_headers)
+ if session.session_id:
+ _mcp_terminate_session(client, session.url, session_headers)
except (SSRFBlockedError, httpx.ProxyError) as exc:
raise ToolsFetchError(
"Upstream MCP connection blocked. Ask an administrator to check the outbound proxy configuration."
@@ -192,17 +218,15 @@ def call_upstream_tool(
max_response_bytes=MAX_RESPONSE_BYTES,
trust_env=trust_environment_proxy(installation.url, installation.team_id),
) as client:
- session_id, upstream_url = _mcp_initialize(client, installation.url, base_headers)
- session_headers = dict(base_headers)
- if session_id:
- session_headers["Mcp-Session-Id"] = session_id
+ session = _mcp_initialize(client, installation.url, base_headers)
+ session_headers = session.headers(base_headers)
- _mcp_send_initialized(client, upstream_url, session_headers)
+ _mcp_send_initialized(client, session.url, session_headers)
try:
- return _mcp_call_tool(client, upstream_url, session_headers, tool_name, arguments)
+ return _mcp_call_tool(client, session.url, session_headers, tool_name, arguments)
finally:
- if session_id:
- _mcp_terminate_session(client, upstream_url, session_headers)
+ if session.session_id:
+ _mcp_terminate_session(client, session.url, session_headers)
except (SSRFBlockedError, httpx.ProxyError) as exc:
raise ToolCallError(
"Upstream MCP connection blocked. Ask an administrator to check the outbound proxy configuration."
@@ -231,14 +255,31 @@ def _post_with_same_origin_redirect(
return client.post(redirect_url, content=content, headers=headers), redirect_url
-def _mcp_initialize(client: httpx.Client, url: str, headers: dict[str, str]) -> tuple[str | None, str]:
+def _mcp_initialize(client: httpx.Client, url: str, headers: dict[str, str]) -> _UpstreamSession:
+ """Open a session, offering the newest protocol version first.
+
+ Some servers reject a version they don't support instead of answering with
+ one they do, so a rejection moves on to the next older version.
+ """
+ *newer_versions, oldest_version = SUPPORTED_PROTOCOL_VERSIONS
+ for offered_version in newer_versions:
+ try:
+ return _mcp_initialize_with_version(client, url, headers, offered_version)
+ except _OfferRejected:
+ continue
+ return _mcp_initialize_with_version(client, url, headers, oldest_version)
+
+
+def _mcp_initialize_with_version(
+ client: httpx.Client, url: str, headers: dict[str, str], offered_version: str
+) -> _UpstreamSession:
body = json.dumps(
{
"jsonrpc": "2.0",
"id": _INITIALIZE_ID,
"method": "initialize",
"params": {
- "protocolVersion": _PROTOCOL_VERSION,
+ "protocolVersion": offered_version,
"capabilities": {},
"clientInfo": _CLIENT_INFO,
},
@@ -251,19 +292,37 @@ def _mcp_initialize(client: httpx.Client, url: str, headers: dict[str, str]) ->
"initialize request returned error",
url=upstream_url,
status_code=response.status_code,
+ offered_protocol_version=offered_version,
body=response.text[:500],
)
- raise ToolsFetchError(f"Upstream initialize returned status {response.status_code}")
+ error_class = _OfferRejected if response.status_code == 400 else ToolsFetchError
+ raise error_class(f"Upstream initialize returned status {response.status_code}")
payload = _parse_jsonrpc_response(
response.text, response.headers.get("content-type", ""), _INITIALIZE_ID, request_name="initialize"
)
if isinstance(payload, dict) and payload.get("error"):
- raise ToolsFetchError(f"Upstream initialize returned error: {payload['error']}")
+ raise _OfferRejected(f"Upstream initialize returned error: {payload['error']}")
+
+ result = payload.get("result") if isinstance(payload, dict) else None
+ answered_version = result.get("protocolVersion") if isinstance(result, dict) else None
+ if answered_version not in SUPPORTED_PROTOCOL_VERSIONS:
+ # A server that answers with an unknown version can still work, so the sync continues without the header.
+ logger.warning(
+ "initialize answered with an unsupported protocol version",
+ host=urlparse(upstream_url).hostname,
+ offered_protocol_version=offered_version,
+ answered_protocol_version=str(answered_version)[:50],
+ )
+ answered_version = None
# Session id is optional per the spec — servers that don't need one still
# work with tools/list, so treat a missing header as "no session needed".
- return response.headers.get("mcp-session-id"), upstream_url
+ return _UpstreamSession(
+ session_id=response.headers.get("mcp-session-id"),
+ url=upstream_url,
+ protocol_version=answered_version,
+ )
def _mcp_send_initialized(client: httpx.Client, url: str, headers: dict[str, str]) -> None:
@@ -414,21 +473,23 @@ def _parse_jsonrpc_response(
) from exc
-def sync_installation_tools(installation: MCPServerInstallation) -> list[MCPServerInstallationTool]:
+def sync_installation_tools(installation: MCPServerInstallation) -> UpstreamToolList:
"""Upsert tool rows for an installation against the latest upstream ``tools/list``.
- New tools are inserted with ``approval_state="needs_approval"`` (explicit opt-in).
- Existing tools keep their approval state; name/description/schema/annotations/last_seen_at are updated.
- Tools that disappear upstream get ``removed_at`` set (approval state preserved for later).
- Tools that reappear get ``removed_at`` cleared.
+
+ Returns the upstream listing it applied.
"""
- upstream_tools = fetch_upstream_tools(installation)
+ upstream = fetch_upstream_tools(installation)
now = timezone.now()
existing_by_name = {t.tool_name: t for t in installation.tools.all()}
seen_names: set[str] = set()
- for tool in upstream_tools:
+ for tool in upstream.tools:
tool_name = tool["name"]
seen_names.add(tool_name)
display_name = tool.get("title") or tool.get("displayName") or ""
@@ -488,7 +549,7 @@ def sync_installation_tools(installation: MCPServerInstallation) -> list[MCPServ
row.removed_at = now
row.save(update_fields=["removed_at", "updated_at"])
- return list(installation.tools.all())
+ return upstream
def resync_installation_tools(installation: MCPServerInstallation) -> bool:
diff --git a/products/mcp_store/frontend/gateway/GatewayServerAccess.tsx b/products/mcp_store/frontend/gateway/GatewayServerAccess.tsx
index c8ae13d2c577..75285cd5cd1a 100644
--- a/products/mcp_store/frontend/gateway/GatewayServerAccess.tsx
+++ b/products/mcp_store/frontend/gateway/GatewayServerAccess.tsx
@@ -153,9 +153,9 @@ export function GatewayAccessSection(): JSX.Element | null {
</LemonButton>
</div>
<div className="text-sm text-secondary">
- You share your own {server.name} connection, and each teammate shares theirs. Pick whether an agent uses
- it only for your runs or for every agent run in this project. Teammates can't use the connection
- directly, but agents can act through it on their runs.
+ Agents only use your {server.name} connection if you share it. With "Only me", an agent uses it on runs
+ you start. With "Everyone in this project", any agent run in this project can use it, including scouts,
+ automatic support replies, and your teammates' runs.
</div>
{server.agents.length === 0 ? (
diff --git a/products/mcp_store/frontend/gateway/mcpGatewayLogic.test.ts b/products/mcp_store/frontend/gateway/mcpGatewayLogic.test.ts
index dd160fed7168..fdae696a6db3 100644
--- a/products/mcp_store/frontend/gateway/mcpGatewayLogic.test.ts
+++ b/products/mcp_store/frontend/gateway/mcpGatewayLogic.test.ts
@@ -215,6 +215,7 @@ function installation(): MCPServerInstallationApi {
return {
id: 'installation-id',
template_id: null,
+ gateway_server_id: null,
name: 'Custom server',
icon_key: '',
icon_domain: '',
diff --git a/products/mcp_store/frontend/generated/api.schemas.ts b/products/mcp_store/frontend/generated/api.schemas.ts
index 6dc494f22fdc..fdc0dd4c3982 100644
--- a/products/mcp_store/frontend/generated/api.schemas.ts
+++ b/products/mcp_store/frontend/generated/api.schemas.ts
@@ -868,6 +868,11 @@ export interface MCPServerInstallationApi {
readonly id: string
/** @nullable */
readonly template_id: string | null
+ /**
+ * ID of the MCP server this connection belongs to. The MCP server page takes this ID, not the connection id. Null for older connections that are not linked to a server yet.
+ * @nullable
+ */
+ readonly gateway_server_id: string | null
readonly name: string
/** Deprecated: use icon_domain instead. Lowercase key from the linked template for clients that still render bundled icon assets. Empty if custom install (no template). */
readonly icon_key: string
diff --git a/products/mcp_store/frontend/mcpStoreLogic.test.ts b/products/mcp_store/frontend/mcpStoreLogic.test.ts
index 5aa63681d422..2365394260c7 100644
--- a/products/mcp_store/frontend/mcpStoreLogic.test.ts
+++ b/products/mcp_store/frontend/mcpStoreLogic.test.ts
@@ -13,6 +13,7 @@ function installation(id: string, url?: string): MCPServerInstallationApi {
return {
id,
template_id: null,
+ gateway_server_id: null,
name: id,
description: '',
icon_key: '',
diff --git a/products/mcp_store/mcp/tools.yaml b/products/mcp_store/mcp/tools.yaml
index 71f3177b479b..979425344bd9 100644
--- a/products/mcp_store/mcp/tools.yaml
+++ b/products/mcp_store/mcp/tools.yaml
@@ -37,6 +37,8 @@ tools:
title: List MCP connections
description: >
List the MCP servers connected to this project (the "connections"). Each entry returns its `id` (the
- connection id you pass to mcp-connection-tools-list), `display_name`, `url`, and status fields
- (`is_enabled`, `needs_reauth`, `pending_oauth`) plus `tool_count`. Use this to discover which connections
- exist before loading a connection's live tool catalog with mcp-connection-tools-list.
+ connection id you pass to mcp-connection-tools-list), `gateway_server_id` (the id of the MCP server the
+ connection belongs to), `display_name`, `url`, and status fields (`is_enabled`, `needs_reauth`,
+ `pending_oauth`) plus `tool_count`. Use this to discover which connections exist before loading a
+ connection's live tool catalog with mcp-connection-tools-list. To link to a server's page with
+ generate-app-url (`mcpGatewayServer`), pass `gateway_server_id`, never the connection `id`.
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index 1cdca784086b..ae70bd4522c4 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -10886,7 +10886,7 @@
}
},
"mcp-connections-list": {
- "description": "List the MCP servers connected to this project (the \"connections\"). Each entry returns its `id` (the connection id you pass to mcp-connection-tools-list), `display_name`, `url`, and status fields (`is_enabled`, `needs_reauth`, `pending_oauth`) plus `tool_count`. Use this to discover which connections exist before loading a connection's live tool catalog with mcp-connection-tools-list.",
+ "description": "List the MCP servers connected to this project (the \"connections\"). Each entry returns its `id` (the connection id you pass to mcp-connection-tools-list), `gateway_server_id` (the id of the MCP server the connection belongs to), `display_name`, `url`, and status fields (`is_enabled`, `needs_reauth`, `pending_oauth`) plus `tool_count`. Use this to discover which connections exist before loading a connection's live tool catalog with mcp-connection-tools-list. To link to a server's page with generate-app-url (`mcpGatewayServer`), pass `gateway_server_id`, never the connection `id`.",
"category": "MCP Store",
"feature": "mcp_store",
"summary": "List MCP connections",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 1553590ff61b..293a65504563 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -11330,7 +11330,7 @@
}
},
"mcp-connections-list": {
- "description": "List the MCP servers connected to this project (the \"connections\"). Each entry returns its `id` (the connection id you pass to mcp-connection-tools-list), `display_name`, `url`, and status fields (`is_enabled`, `needs_reauth`, `pending_oauth`) plus `tool_count`. Use this to discover which connections exist before loading a connection's live tool catalog with mcp-connection-tools-list.",
+ "description": "List the MCP servers connected to this project (the \"connections\"). Each entry returns its `id` (the connection id you pass to mcp-connection-tools-list), `gateway_server_id` (the id of the MCP server the connection belongs to), `display_name`, `url`, and status fields (`is_enabled`, `needs_reauth`, `pending_oauth`) plus `tool_count`. Use this to discover which connections exist before loading a connection's live tool catalog with mcp-connection-tools-list. To link to a server's page with generate-app-url (`mcpGatewayServer`), pass `gateway_server_id`, never the connection `id`.",
"category": "MCP Store",
"feature": "mcp_store",
"summary": "List MCP connections",
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 46ef0cd0109a..4aedcc697727 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -64262,6 +64262,11 @@ export namespace Schemas {
readonly id: string;
/** @nullable */
readonly template_id: string | null;
+ /**
+ * ID of the MCP server this connection belongs to. The MCP server page takes this ID, not the connection id. Null for older connections that are not linked to a server yet.
+ * @nullable
+ */
+ readonly gateway_server_id: string | null;
readonly name: string;
/** Deprecated: use icon_domain instead. Lowercase key from the linked template for clients that still render bundled icon assets. Empty if custom install (no template). */
readonly icon_key: string;