Add MCP server tool filtering support to agents-js #164

vrtnis · 2025-07-01T01:31:36Z

Hey all - this PR brings a new tool filtering feature to our MCP integrations. This resolves #162 based on openai/openai-agents-python#861

You can now:

Use createStaticToolFilter for quick allow/block lists
Provide a custom filter function to make dynamic decisions based on runContext
Updated core API so getAllTools now accepts your runContext, ensuring filters are applied correctly
Documentation enhancements in docs/guides/mcp.mdx
New example (examples/mcp/tool-filter-example.ts) to demonstrate both static and dynamic filtering
Comprehensive tests covering static lists, callable filters, multi-server hierarchies, and cache interactions

All tests pass and you can try it out by pnpm -F mcp start:tool-filter

changeset-bot · 2025-07-01T01:31:41Z

🦋 Changeset detected

Latest commit: 161965f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@openai/agents-realtime	Patch
@openai/agents-core	Patch
@openai/agents	Patch
@openai/agents-openai	Patch
@openai/agents-extensions	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

dkundel-openai · 2025-07-04T02:24:17Z

@seratch can you review please?

seratch

Thanks for sending this! I haven't verified the actual behavior yet but let me share a few quick comments

.changeset/hungry-suns-search.md

docs/src/content/docs/guides/mcp.mdx

packages/agents-core/src/shims/mcp-server/node.ts

vrtnis · 2025-07-10T22:05:13Z

thanks for the comments, @seratch! esp. the point about moving filtering logic that makes sense for keeping the server implementation focused on transport.
i’ve pushed an update that moves filtering into the agent and runner layer, where it can be handled with proper context. look forward to your feedback!

packages/agents-core/src/mcp.ts

vrtnis · 2025-07-11T03:49:44Z

Thanks @seratch. That makes sense and i’ve removed the runContext and agent from the call to underlying.listTools(), so that now filtering happens entirely in getAllMcpFunctionTools() on the agent side.

packages/agents-core/src/mcp.ts

seratch

Sorry, one more request from me

packages/agents-core/src/mcpUtil.ts

packages/agents-core/src/mcp.ts

seratch

Did thorough review and I found your current implementation actually does nothing for allowing/blocking tools. I've implemented draft version of change here: seratch@73eb37a Hope sharing this clarifies things!

examples/mcp/tool-filter-example.ts

seratch · 2025-07-16T06:56:04Z

examples/mcp/tool-filter-example.ts

+      console.log('\nAttempting to write a file (should be blocked):');
+      result = await run(
+        agent,
+        'Create a file named test.txt with the text "hello"',


currently this is blocked either way because the mcp server has the access only to sample_files/

my diff changed this as well

Resolved through merge of 73eb37a, example updated accordingly. Also, e4ba592 explicitly lists sample_files to allow listing.

thanks for sharing your draft, @seratch! You’re absolutely right, my plumbing additions never actually invoked the filter, so allow/block lists weren’t doing anything.

I’ve since merged your implementation from 73eb37a and used that as the foundation. Appreciate the clarity your diff brought to this.

One question: should we also update the test to explicitly include toolUseBehavior: 'stop_on_first_tool' in the agent config? That setting ensures the run exits immediately with a "Tool \"write_file\" is blocked by MCP filter." error rather than continuing or looping, which might make the filter behavior clearer and more predictable in test output.

happy to add that if helpful!

Thanks for pointing this out. I agree the agent should behave in the way you mentioned for the scenario. Adding test patterns would be appreciated!

Just added an integration test, i.e., mcpToolFilter.integration.test.ts that spins up the stub FS server and verifies that list_directory (allowed) works and write_file (blocked) gets immediately rejected with the expected message using toolUseBehavior: 'stop_on_first_tool'.

I also expanded the original unit tests to cover no filter, allow-only, block-only, async filters, thrown errors, and cache invalidation. This should give us better coverage across edge cases.

Lastly, I added a script to package.json so the example can now be run via pnpm examples:tool-filter.

Thoughts? Let me know if we should have anything else covered!

Noticed that CI had failed on the merge commit (b5ff9ac) due to a type issue with modelResponses in the integration test. I fixed it by adding the correct ModelResponse[] type. It should be good now.

seratch

The changes are now all good, but there are a few things to adjust 🙏

.changeset/heavy-yaks-mate.md

seratch · 2025-07-28T06:15:51Z

docs/src/content/docs/guides/mcp.mdx

+You can restrict which tools are exposed from each server. Pass either a static filter
+using `createMCPToolStaticFilter` or a custom function:
+
+```ts


We consistently use compiled code snippets in docs. can you do this?

Add examples/docs/mcp/tool-filter.ts, which compiles and works

Add import stdioExample from '../../../../../examples/docs/mcp/tool-filter.ts?raw'; and use it here

If you're unsure or don't have time for this, please just remove this change.

Yes, good point. I've added the example as suggested. Confirmed that it compiles and works (screenshot attached).

Co-authored-by: Kazuhiro Sera <[email protected]>

…sts and server impl

- Moved tool filtering logic to agent/runner layer - Removed server-side filtering and context coupling - Updated test suite to reflect new behavior

Reverts prior tool filtering interface changes and updates corresponding tests.

* Handle function call messages with empty content * Resolve test failure * Create heavy-yaks-mate.md --------- Co-authored-by: Dominik Kundel <[email protected]>

… to getAllMcpTools

… changeset

seratch

LGTM

seratch · 2025-07-28T07:35:43Z

@vrtnis Thank you so much for working on this PR 👏

vrtnis · 2025-07-28T07:45:10Z

Thanks @seratch, appreciate the thoughtful reviews and guidance throughout. Learned a lot working through this one! 🙌

--------- Co-authored-by: Kazuhiro Sera <[email protected]>

seratch added enhancement New feature or request package:agents-core package:agents-realtime labels Jul 7, 2025

seratch self-assigned this Jul 7, 2025

seratch requested changes Jul 10, 2025

View reviewed changes

.changeset/hungry-suns-search.md Outdated Show resolved Hide resolved

docs/src/content/docs/guides/mcp.mdx Outdated Show resolved Hide resolved

packages/agents-core/src/shims/mcp-server/node.ts Outdated Show resolved Hide resolved

seratch requested changes Jul 11, 2025

View reviewed changes

packages/agents-core/src/mcp.ts Outdated Show resolved Hide resolved

seratch reviewed Jul 15, 2025

View reviewed changes

packages/agents-core/src/mcp.ts Outdated Show resolved Hide resolved

seratch requested changes Jul 15, 2025

View reviewed changes

packages/agents-core/src/mcpUtil.ts Outdated Show resolved Hide resolved

packages/agents-core/src/mcp.ts Outdated Show resolved Hide resolved

vrtnis force-pushed the feat/mcp-tool-filtering-js branch from 4dce2d5 to 47ae347 Compare July 15, 2025 17:53

seratch requested changes Jul 16, 2025

View reviewed changes

vrtnis force-pushed the feat/mcp-tool-filtering-js branch from b73a090 to 5ab34ae Compare July 25, 2025 01:56

seratch requested changes Jul 28, 2025

View reviewed changes

vrtnis and others added 14 commits July 27, 2025 23:34

docs(mcp): document tool filtering

48ebb1c

fix(realtime): narrow currentAgent type for getAllTools

39f74dd

feat(examples): add MCP tool-filter example

4161253

chore: add changeset for MCP tool-filtering support (fixes openai#162)

0e7694b

Update .changeset/hungry-suns-search.md

74cc833

Co-authored-by: Kazuhiro Sera <[email protected]>

Update docs/src/content/docs/guides/mcp.mdx

14fbfc1

Co-authored-by: Kazuhiro Sera <[email protected]>

refactor: integrate filtered tool logic into agent-level, clean up te…

2ddaea8

…sts and server impl

refactor(core): update MCP tool filtering implementation

66b6c6b

- Moved tool filtering logic to agent/runner layer - Removed server-side filtering and context coupling - Updated test suite to reflect new behavior

revert: restore MCPServer interface and listTools signature

4e5c53d

Reverts prior tool filtering interface changes and updates corresponding tests.

refactor(core): prefix tool filter names with MCP

d7ab6fd

Handle function call messages with empty content (openai#203)

eeaa067

* Handle function call messages with empty content * Resolve test failure * Create heavy-yaks-mate.md --------- Co-authored-by: Dominik Kundel <[email protected]>

wip

04297fa

chore(example): update tool-filter example after seratch 73eb37a merge

d37724f

test(agents-core): fix mcpCache tests by passing RunContext and Agent…

957fc8b

… to getAllMcpTools

vrtnis added 3 commits July 27, 2025 23:34

test: expand unit tests and add MCP filter integration test

803d9e2

test: fix modelResponses typing for FakeModel in MCP integration test

26a2746

docs: update MCP guide, add tool-filter example, and remove unrelated…

161965f

… changeset

vrtnis force-pushed the feat/mcp-tool-filtering-js branch from bb41f61 to 161965f Compare July 28, 2025 07:26

seratch approved these changes Jul 28, 2025

View reviewed changes

seratch merged commit 08dd469 into openai:main Jul 28, 2025
5 checks passed

vrtnis added a commit to vrtnis/openai-agents-js that referenced this pull request Jul 28, 2025

Add MCP server tool filtering support to agents-js (openai#164)

c78a2c4

--------- Co-authored-by: Kazuhiro Sera <[email protected]>

xierenyuan mentioned this pull request Aug 5, 2025

getAllMcpTools introduced breaking changes #295

Closed

vrtnis mentioned this pull request Aug 5, 2025

refactor: restructure mcp tools fetching with options object pattern #296

Merged

Add MCP server tool filtering support to agents-js #164

Add MCP server tool filtering support to agents-js #164

Conversation

vrtnis commented Jul 1, 2025

Uh oh!

changeset-bot bot commented Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

dkundel-openai commented Jul 4, 2025

Uh oh!

seratch left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vrtnis commented Jul 10, 2025

Uh oh!

Uh oh!

vrtnis commented Jul 11, 2025

Uh oh!

Uh oh!

seratch left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

seratch left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seratch left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seratch left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

seratch commented Jul 28, 2025

Uh oh!

vrtnis commented Jul 28, 2025

Uh oh!

Uh oh!

changeset-bot bot commented Jul 1, 2025 •

edited

Loading