Skip to content

Commit 9a21ab1

Browse files
authored
feat(mcp): add configurable MCP listing page limits (#5133)
1 parent a58d03c commit 9a21ab1

4 files changed

Lines changed: 283 additions & 11 deletions

File tree

‎src/agents/mcp/server.py‎

Lines changed: 63 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -892,6 +892,7 @@ def __init__(
892892
*,
893893
tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None,
894894
tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None,
895+
max_list_pages: int | None = None,
895896
):
896897
"""
897898
Args:
@@ -935,6 +936,12 @@ def __init__(
935936
server before the tool is invoked.
936937
tool_output_guardrails: Optional list of guardrails applied to every tool on this
937938
server after the tool returns.
939+
max_list_pages: Maximum successful pages per automatic `list_tools()` or
940+
`list_prompts()` call. Set a positive integer to bound pagination; `None`
941+
(the default) applies no page limit. A final page at the limit succeeds;
942+
otherwise `UserError` is raised without returning or caching a partial list.
943+
Failed requests follow the existing retry policy and do not reset this budget.
944+
This does not limit page size or apply to explicit resource pagination.
938945
"""
939946
mcp_compat.enable_legacy_httpx_compat()
940947
super().__init__(
@@ -957,6 +964,12 @@ def __init__(
957964
# the public timeout attribute before a later connection attempt.
958965
_client_session_read_timeout(client_session_timeout_seconds)
959966
_validate_retry_backoff_seconds_max(retry_backoff_seconds_max)
967+
if max_list_pages is not None:
968+
if isinstance(max_list_pages, bool) or not isinstance(max_list_pages, int):
969+
raise TypeError("max_list_pages must be a positive integer or None.")
970+
if max_list_pages < 1:
971+
raise ValueError("max_list_pages must be a positive integer or None.")
972+
self.max_list_pages = max_list_pages
960973
self.client_session_timeout_seconds = client_session_timeout_seconds
961974
self.max_retry_attempts = max_retry_attempts
962975
self.retry_backoff_seconds_base = retry_backoff_seconds_base
@@ -1454,23 +1467,28 @@ async def list_tools(
14541467
cursor: str | None = None
14551468
seen_cursors: set[str | None] = set()
14561469

1457-
async def fetch_pages() -> bool:
1470+
async def fetch_pages() -> Literal["complete", "repeated_cursor", "page_limit"]:
14581471
nonlocal cursor
14591472
while True:
1473+
if (
1474+
self.max_list_pages is not None
1475+
and len(seen_cursors) >= self.max_list_pages
1476+
):
1477+
return "page_limit"
14601478
result = await self._list_tools_page(session, cursor)
14611479
tools.extend(result.tools)
14621480
seen_cursors.add(cursor)
14631481
next_cursor = result_next_cursor(result)
14641482
if next_cursor is None:
1465-
return True
1483+
return "complete"
14661484
if next_cursor in seen_cursors:
1467-
return False
1485+
return "repeated_cursor"
14681486
cursor = next_cursor
14691487

1470-
pagination_complete = False
1488+
pagination_status: str | None = None
14711489
pagination_failure: BaseException | None = None
14721490
try:
1473-
pagination_complete = await self._run_with_retries(fetch_pages)
1491+
pagination_status = await self._run_with_retries(fetch_pages)
14741492
except BaseException as error:
14751493
if cursor is None:
14761494
raise
@@ -1483,13 +1501,18 @@ async def fetch_pages() -> bool:
14831501
else:
14841502
pagination_failure = _credential_safe_exception_leaf(error)
14851503

1486-
if pagination_failure is not None or not pagination_complete:
1504+
if pagination_failure is not None or pagination_status != "complete":
14871505
cursor = None
14881506
seen_cursors.clear()
14891507
tools.clear()
14901508
del fetch_pages
14911509
if pagination_failure is not None:
14921510
raise pagination_failure from None
1511+
if pagination_status == "page_limit":
1512+
raise UserError(
1513+
"MCP tool listing exceeded max_list_pages. Increase max_list_pages "
1514+
"to allow more pages, or check the server pagination."
1515+
) from None
14931516
raise UserError(
14941517
f"MCP server '{self._error_name}' returned a repeated cursor while "
14951518
"listing tools."
@@ -1646,9 +1669,13 @@ async def list_prompts(
16461669
seen_cursors: set[str | None] = {None}
16471670
pagination_failure: BaseException | None = None
16481671
repeated_cursor = False
1672+
page_limit_reached = False
16491673
page: ListPromptsResult | None = None
16501674
next_cursor: str | None = None
16511675
while cursor is not None:
1676+
if self.max_list_pages is not None and len(seen_cursors) >= self.max_list_pages:
1677+
page_limit_reached = True
1678+
break
16521679
try:
16531680
page = await self._list_prompts_page(session, cursor)
16541681
except BaseException as error:
@@ -1669,7 +1696,7 @@ async def list_prompts(
16691696
break
16701697
cursor = next_cursor
16711698

1672-
if pagination_failure is not None or repeated_cursor:
1699+
if pagination_failure is not None or repeated_cursor or page_limit_reached:
16731700
cursor = None
16741701
seen_cursors.clear()
16751702
prompts.clear()
@@ -1678,6 +1705,11 @@ async def list_prompts(
16781705
del result
16791706
if pagination_failure is not None:
16801707
raise pagination_failure from None
1708+
if page_limit_reached:
1709+
raise UserError(
1710+
"MCP prompt listing exceeded max_list_pages. Increase max_list_pages "
1711+
"to allow more pages, or check the server pagination."
1712+
) from None
16811713
raise UserError(
16821714
f"MCP server '{self._error_name}' returned a repeated cursor while listing prompts."
16831715
) from None
@@ -1913,6 +1945,7 @@ def __init__(
19131945
*,
19141946
tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None,
19151947
tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None,
1948+
max_list_pages: int | None = None,
19161949
):
19171950
"""Create a new MCP server based on the stdio transport.
19181951
@@ -1961,6 +1994,12 @@ def __init__(
19611994
server before the tool is invoked.
19621995
tool_output_guardrails: Optional list of guardrails applied to every tool on this
19631996
server after the tool returns.
1997+
max_list_pages: Maximum successful pages per automatic `list_tools()` or
1998+
`list_prompts()` call. Set a positive integer to bound pagination; `None`
1999+
(the default) applies no page limit. A final page at the limit succeeds;
2000+
otherwise `UserError` is raised without returning or caching a partial list.
2001+
Failed requests follow the existing retry policy and do not reset this budget.
2002+
This does not limit page size or apply to explicit resource pagination.
19642003
"""
19652004
super().__init__(
19662005
cache_tools_list=cache_tools_list,
@@ -1975,6 +2014,7 @@ def __init__(
19752014
tool_meta_resolver=tool_meta_resolver,
19762015
custom_data_extractor=custom_data_extractor,
19772016
retry_backoff_seconds_max=retry_backoff_seconds_max,
2017+
max_list_pages=max_list_pages,
19782018
tool_input_guardrails=tool_input_guardrails,
19792019
tool_output_guardrails=tool_output_guardrails,
19802020
)
@@ -2055,6 +2095,7 @@ def __init__(
20552095
*,
20562096
tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None,
20572097
tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None,
2098+
max_list_pages: int | None = None,
20582099
):
20592100
"""Create a new MCP server based on the HTTP with SSE transport.
20602101
@@ -2105,6 +2146,12 @@ def __init__(
21052146
server before the tool is invoked.
21062147
tool_output_guardrails: Optional list of guardrails applied to every tool on this
21072148
server after the tool returns.
2149+
max_list_pages: Maximum successful pages per automatic `list_tools()` or
2150+
`list_prompts()` call. Set a positive integer to bound pagination; `None`
2151+
(the default) applies no page limit. A final page at the limit succeeds;
2152+
otherwise `UserError` is raised without returning or caching a partial list.
2153+
Failed requests follow the existing retry policy and do not reset this budget.
2154+
This does not limit page size or apply to explicit resource pagination.
21082155
"""
21092156
super().__init__(
21102157
cache_tools_list=cache_tools_list,
@@ -2119,6 +2166,7 @@ def __init__(
21192166
tool_meta_resolver=tool_meta_resolver,
21202167
custom_data_extractor=custom_data_extractor,
21212168
retry_backoff_seconds_max=retry_backoff_seconds_max,
2169+
max_list_pages=max_list_pages,
21222170
tool_input_guardrails=tool_input_guardrails,
21232171
tool_output_guardrails=tool_output_guardrails,
21242172
)
@@ -2225,6 +2273,7 @@ def __init__(
22252273
*,
22262274
tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None,
22272275
tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None,
2276+
max_list_pages: int | None = None,
22282277
):
22292278
"""Create a new MCP server based on the Streamable HTTP transport.
22302279
@@ -2276,6 +2325,12 @@ def __init__(
22762325
server before the tool is invoked.
22772326
tool_output_guardrails: Optional list of guardrails applied to every tool on this
22782327
server after the tool returns.
2328+
max_list_pages: Maximum successful pages per automatic `list_tools()` or
2329+
`list_prompts()` call. Set a positive integer to bound pagination; `None`
2330+
(the default) applies no page limit. A final page at the limit succeeds;
2331+
otherwise `UserError` is raised without returning or caching a partial list.
2332+
Failed requests follow the existing retry policy and do not reset this budget.
2333+
This does not limit page size or apply to explicit resource pagination.
22792334
"""
22802335
super().__init__(
22812336
cache_tools_list=cache_tools_list,
@@ -2290,6 +2345,7 @@ def __init__(
22902345
tool_meta_resolver=tool_meta_resolver,
22912346
custom_data_extractor=custom_data_extractor,
22922347
retry_backoff_seconds_max=retry_backoff_seconds_max,
2348+
max_list_pages=max_list_pages,
22932349
tool_input_guardrails=tool_input_guardrails,
22942350
tool_output_guardrails=tool_output_guardrails,
22952351
)

‎tests/mcp/test_list_page_limits.py‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
from __future__ import annotations
2+
3+
import asyncio
4+
from typing import Any
5+
from unittest.mock import AsyncMock, MagicMock
6+
7+
import pytest
8+
from mcp.types import PaginatedRequestParams, Prompt
9+
10+
from agents import Agent, Runner, UserError
11+
from agents.mcp import MCPServerSse, MCPServerStdio, MCPServerStreamableHttp
12+
from agents.testing import ScriptedModel
13+
14+
from .model_compat import ListPromptsResult, ListToolsResult, Tool
15+
16+
17+
def make_server(transport: str, **kwargs: Any):
18+
if transport == "stdio":
19+
return MCPServerStdio(params={"command": "unused"}, **kwargs)
20+
if transport == "sse":
21+
return MCPServerSse(params={"url": "https://example.com/mcp"}, **kwargs)
22+
return MCPServerStreamableHttp(params={"url": "https://example.com/mcp"}, **kwargs)
23+
24+
25+
def list_page(method: str, index: int, *, last: bool = False, empty: bool = False):
26+
cursor = None if last else f"private-cursor-{index}"
27+
if method == "list_tools":
28+
return ListToolsResult(
29+
tools=[] if empty else [Tool(name=f"tool_{index}", inputSchema={})],
30+
nextCursor=cursor,
31+
)
32+
return ListPromptsResult(
33+
prompts=[] if empty else [Prompt(name=f"prompt_{index}")],
34+
nextCursor=cursor,
35+
_meta={"page": index},
36+
)
37+
38+
39+
@pytest.mark.parametrize("transport", ["stdio", "sse", "http"])
40+
@pytest.mark.parametrize("limit", [0, -1])
41+
def test_nonpositive_page_limit_rejected_before_connect(transport: str, limit: int):
42+
with pytest.raises(ValueError, match="max_list_pages must be a positive integer or None"):
43+
make_server(transport, max_list_pages=limit)
44+
45+
46+
@pytest.mark.parametrize("limit", [True, 1.5])
47+
def test_page_limit_requires_an_integer(limit: Any):
48+
with pytest.raises(TypeError, match="max_list_pages must be a positive integer or None"):
49+
make_server("stdio", max_list_pages=limit)
50+
51+
52+
@pytest.mark.asyncio
53+
@pytest.mark.parametrize("transport", ["stdio", "sse", "http"])
54+
@pytest.mark.parametrize("method", ["list_tools", "list_prompts"])
55+
@pytest.mark.parametrize("empty", [False, True])
56+
async def test_fresh_cursors_stop_at_page_limit(transport: str, method: str, empty: bool):
57+
server = make_server(
58+
transport, max_list_pages=2, max_retry_attempts=2, retry_backoff_seconds_base=0
59+
)
60+
session = MagicMock()
61+
request = AsyncMock(side_effect=[list_page(method, i, empty=empty) for i in range(4)])
62+
setattr(session, method, request)
63+
server.session = session
64+
65+
with pytest.raises(UserError, match="exceeded max_list_pages"):
66+
await getattr(server, method)()
67+
68+
assert request.await_count == 2
69+
assert server.cached_tools is None
70+
71+
72+
@pytest.mark.asyncio
73+
@pytest.mark.parametrize("method", ["list_tools", "list_prompts"])
74+
@pytest.mark.parametrize("limit", [1, 2, None])
75+
async def test_complete_listing_at_page_boundary(method: str, limit: int | None):
76+
server = make_server("stdio", max_list_pages=limit, cache_tools_list=True)
77+
page_count = limit if limit is not None else 4
78+
session = MagicMock()
79+
request = AsyncMock(
80+
side_effect=[list_page(method, i, last=i == page_count - 1) for i in range(page_count)]
81+
)
82+
setattr(session, method, request)
83+
server.session = session
84+
85+
result = await getattr(server, method)()
86+
87+
prefix = "tool" if method == "list_tools" else "prompt"
88+
entries = result if method == "list_tools" else result.prompts
89+
assert [entry.name for entry in entries] == [f"{prefix}_{i}" for i in range(page_count)]
90+
assert request.await_count == page_count
91+
if method == "list_tools":
92+
assert await server.list_tools() == result
93+
assert request.await_count == page_count
94+
else:
95+
assert result.meta == {"page": 0}
96+
97+
98+
@pytest.mark.asyncio
99+
async def test_failed_refresh_does_not_replace_cache_and_next_call_starts_fresh():
100+
server = make_server("http", max_list_pages=1, cache_tools_list=True)
101+
session = MagicMock()
102+
session.list_tools = AsyncMock(
103+
side_effect=[
104+
list_page("list_tools", 0, last=True),
105+
list_page("list_tools", 1),
106+
list_page("list_tools", 2, last=True),
107+
]
108+
)
109+
server.session = session
110+
original = await server.list_tools()
111+
server.invalidate_tools_cache()
112+
113+
with pytest.raises(UserError, match="exceeded max_list_pages"):
114+
await server.list_tools()
115+
116+
assert server.cached_tools == original
117+
refreshed = await server.list_tools()
118+
assert [tool.name for tool in refreshed] == ["tool_2"]
119+
assert await server.list_tools() == refreshed
120+
assert session.list_tools.await_count == 3
121+
assert all(not call.kwargs for call in session.list_tools.await_args_list)
122+
123+
124+
@pytest.mark.asyncio
125+
@pytest.mark.parametrize("complete", [False, True])
126+
async def test_successful_page_budget_survives_failed_page_retry(complete: bool):
127+
server = make_server(
128+
"stdio", max_list_pages=2, max_retry_attempts=2, retry_backoff_seconds_base=0
129+
)
130+
session = MagicMock()
131+
session.list_tools = AsyncMock(
132+
side_effect=[
133+
list_page("list_tools", 0),
134+
RuntimeError("transient failure"),
135+
list_page("list_tools", 1, last=complete),
136+
list_page("list_tools", 2, last=True),
137+
]
138+
)
139+
server.session = session
140+
141+
if complete:
142+
assert [tool.name for tool in await server.list_tools()] == ["tool_0", "tool_1"]
143+
else:
144+
with pytest.raises(UserError, match="exceeded max_list_pages"):
145+
await server.list_tools()
146+
assert server.cached_tools is None
147+
148+
assert session.list_tools.await_count == 3
149+
assert session.list_tools.await_args_list[1].kwargs == {
150+
"params": PaginatedRequestParams(cursor="private-cursor-0")
151+
}
152+
assert session.list_tools.await_args_list[2] == session.list_tools.await_args_list[1]
153+
154+
155+
@pytest.mark.asyncio
156+
async def test_runner_stops_during_tool_enumeration_before_model_execution():
157+
server = make_server("stdio", max_list_pages=1)
158+
session = MagicMock()
159+
session.list_tools = AsyncMock(return_value=list_page("list_tools", 0))
160+
server.session = session
161+
model = ScriptedModel()
162+
model.get_response = AsyncMock()
163+
164+
with pytest.raises(UserError, match="exceeded max_list_pages"):
165+
await Runner.run(Agent(name="test", model=model, mcp_servers=[server]), "hello")
166+
167+
model.get_response.assert_not_awaited()
168+
assert session.list_tools.await_count == 1
169+
assert server.cached_tools is None
170+
171+
172+
@pytest.mark.asyncio
173+
@pytest.mark.parametrize("method", ["list_tools", "list_prompts"])
174+
async def test_cancellation_with_page_budget_preserves_cancellation(method: str):
175+
server = make_server("http", max_list_pages=2)
176+
session = MagicMock()
177+
request = AsyncMock(side_effect=[list_page(method, 0), asyncio.CancelledError()])
178+
setattr(session, method, request)
179+
server.session = session
180+
181+
with pytest.raises(asyncio.CancelledError):
182+
await getattr(server, method)()
183+
184+
assert request.await_count == 2
185+
assert server.cached_tools is None

0 commit comments

Comments
 (0)