OpenAI Agents SDK tool guardrails: how to use them on MCP tools, and what they skip

The short answer

In the OpenAI Agents SDK for Python, a tool input guardrail runs before a function tool executes and can skip the call, replace its output with a message, or raise a tripwire. A tool output guardrail runs after the tool and can replace the output or raise a tripwire.¹ You attach them with tool_input_guardrails and tool_output_guardrails, on a single tool or on a local MCP server, where they apply to every tool the server exposes.¹

They don’t cover everything. The docs list what they skip: handoffs, hosted tools including HostedMCPTool, built-in execution tools including ShellTool and ComputerTool, and agents used as tools.¹ If your agent can run shell commands or use a hosted MCP server, those calls need a different control.

Three kinds of guardrail

The SDK uses the word guardrail for three different checks, and they run at different moments.

The first row is the trap. By default, agent input guardrails run concurrently with the agent, so the agent may already have consumed tokens or run tools before a tripwire cancels it. Setting run_in_parallel=False makes them finish before the agent starts.¹ If a guardrail is meant to stop something, it must finish before the thing it stops.

For tool calls, the tool input guardrail is the one that matters. It sees the tool’s name and arguments and runs before the side effect.

A tool input guardrail on an MCP server

Local MCP servers (MCPServerStdio, MCPServerStreamableHttp, and the older SSE transport) accept guardrails directly, and the SDK attaches them to every MCP tool that remains after filtering.² Here is a guardrail that refuses SQL that drops or truncates, attached to a database MCP server:

Code Program code, for developers. The text around it says what it does.

import json, re
from agents import Agent, Runner, ToolGuardrailFunctionOutput, tool_input_guardrail
from agents.mcp import MCPServerStdio

DESTRUCTIVE = re.compile(r"\b(drop|truncate)\b", re.I)

@tool_input_guardrail
def no_drop_or_truncate(data):
    args = json.loads(data.context.tool_arguments or "{}")
    sql = str(args.get("sql") or args.get("query") or "")
    if DESTRUCTIVE.search(sql):
        return ToolGuardrailFunctionOutput.reject_content(
            "DROP and TRUNCATE are not allowed from this agent. Ask the user to run it."
        )
    return ToolGuardrailFunctionOutput.allow()

async def main():
    async with MCPServerStdio(
        name="db",
        params={"command": "npx", "args": ["-y", "your-postgres-mcp-server"]},
        tool_input_guardrails=[no_drop_or_truncate],
    ) as server:
        agent = Agent(name="orders", mcp_servers=[server])
        print((await Runner.run(agent, "Clean up the orders table")).final_output)

The shape follows the SDK’s own examples: parse data.context.tool_arguments, return reject_content(...) to refuse with a message the model reads, or allow().²

Two things to know about this pattern. The regular expression is a placeholder: DROP inside a comment trips it, and SQL split across separate calls passes it. A real check parses the SQL. And reject_content returns a message to the model, which will usually try something else. That is what you want for a refusal, but log it, because a model that keeps trying is worth knowing about.

The tools guardrails don’t see

This list, from the SDK’s guardrails page, is the most useful thing to check against your own agent.¹

The shell row deserves attention. An agent with ShellTool can run psql with any SQL in it, and no tool guardrail sees that call. The same goes for ApplyPatchTool writing files. If you give an agent those tools, the control has to live outside the SDK: in the sandbox, the operating system user, or the credentials the shell can reach.

Hosted MCP is the other gap. Because OpenAI’s infrastructure makes the call, your process never gets a chance to inspect it. What you do get is approval: HostedMCPTool takes require_approval in its tool_config, with an on_approval_request callback for deciding in Python.²

Guardrails, filters and approvals together

The SDK offers three controls for MCP tools, and they combine well.

1. Filters decide which tools exist. create_static_tool_filter takes an allow list and a block list, applying the allow list first. A callable filter can decide per agent.² A tool that isn’t listed can’t be called, which beats any check on its arguments.
2. Approvals decide whether a person must say yes. Local servers take require_approval: always, never, a per-tool map, or a callable. The callable doesn’t receive the call’s arguments, so it can only decide by tool name.²
3. Guardrails decide on the arguments. They are the only one of the three that sees what the call will actually do.

Order matters too. For a tool that needs approval, input guardrails normally run after the approval, just before execution. ToolExecutionConfig(pre_approval_tool_input_guardrails=True) runs them before the approval prompt, and the call is still rechecked after.¹ Running them first saves a person from approving a call that would have been refused anyway.

A checklist for an Agents SDK app

1. List every tool the agent has, and mark which rows of the table above they fall in.
2. Filter MCP tools down to the ones the task needs.²
3. Put tool input guardrails on each local MCP server that can write.²
4. Require approval for writes, by tool name, and run guardrails before approval.¹
5. Set run_in_parallel=False on any agent input guardrail meant to block.¹
6. Treat ShellTool and hosted tools as unguarded and limit them some other way.¹
7. Keep a record of refusals and approvals outside the model’s context, so you can review them later.

Where an outside gate fits

Guardrails live inside your Python process, next to the agent. That is convenient, and it means anything that runs outside that pipeline, or a second agent built without your guardrails, goes unchecked. An outside gate sits between the agent and the system it writes to, so every client meets the same rules.

We build one, Deedglass. Its docs carry recipes for nine agent frameworks, including the OpenAI Agents SDK, each a runnable file of 15 lines or fewer with pinned packages; no live model run backs them.³ The OpenAI recipe hands the agent Deedglass’s MCP server through MCPServerStdio, so its calls meet a tool-call policy and risky ones wait for a person’s approval. It is the same local-MCP path as the guardrail above, so it has the same gaps: it doesn’t see ShellTool or hosted MCP calls. For approvals on MCP tool calls in general, see our approvals post; for checks on the tool list itself, tool poisoning. To try the checks without installing anything, open the playground; to grade what an agent can reach on your own machine, run npx deedglass scan (the grade, explained).

Written with AI assistance and checked against our claims register.