Get started
Wrap a tool, see what your agent did, then turn on blocking.
Pick your language
This path is for a TypeScript tool your code calls directly, a Vercel AI SDK tool() or any object with an execute function, not behind an MCP server. If your agent reaches its tools through MCP servers instead, the keyless agentx-mcp proxy protects those today with no code change and no key: switch to the MCP tab above.
This path is for MCP servers your client launches itself, the ones with a command entry in your mcp.json (Claude Code, Cursor, Claude Desktop, Windsurf, VS Code). agentx-mcp wraps that command, so every tools/call is screened before it reaches the server. If your tools are Python functions in your own process, the decorator is your path: switch to the Python tab above.
A remote MCP server your client reaches over HTTP is not wrapped this way today. If that is your setup, tell us in our Discord (the bugs and feature requests channel) so we know who needs it.
01Install
One decorator, @agentx_protect(agent_id="my_agent"), on any tool checks every call inside your own process before it runs, no key.
pip install agentx-security-sdkimport requests
from agentx_sdk import agentx_protect
@agentx_protect(agent_id="crm")
def call_api(url):
return requests.get(url)
# the agent picks the url at runtime:
call_api("http://169.254.169.254/")The tool behaves exactly as it does today: the wrap watches and records, and blocks nothing. Add posture="enforce" to the decorator above when you want it stopping calls, and it keeps blocking until you delete the argument. See what it recorded with agentx audit
Step up to the gateway below for more rules and Recover.
The install is all step 02 needs. The decorator comes at step 03.
02See a call stopped
Watch a prompt-injected DROP TABLE get blocked in ten seconds, offline, with no key and no gateway:
agentx demo # watch a prompt-injected DROP TABLE get blocked03Wrap your own tool, then read the record
One decorator on the tool function. Nothing is blocked yet, so your agent behaves exactly as it does today.
from agentx_sdk import agentx_protect
@agentx_protect(agent_id="crm_worker")
def run_sql(query: str, db=None):
...Run your agent, then from the folder it runs in:
agentx audit # grouped by toolA sample, shortened. Your tools and numbers will differ:
TOOL CALLS SURFACE ARGUMENTS
-----------------------------------------------------------------------
fetch_invoice_pdf 1 HTTP url
issue_refund 1 - amount, currency +2 more
largest amount passed: >=1,000
run_sql 1 DB db_session, query
1 call tripped a policy.
1 ran because nothing was blocking at the time.Calls are recorded whether blocking is on or off. Only wrapped tools appear here, so this is not all your agent did.
04Turn on blocking
Add posture="enforce" to the decorator for one tool, or set it for a whole run:
AGENTX_POSTURE=enforce python your_agent.py # mac/linux$env:AGENTX_POSTURE="enforce"; python your_agent.py # PowerShellThe dangerous call then never runs. It comes back as a value, not an error, carrying coaching your agent can retry on, so check it before you use it:
from agentx_sdk import is_block
out = run_sql(query=agent_query, db=session)
if is_block(out):
# str(out) says what was unsafe and the safe path to take.
revised_query = your_llm(str(out))
out = run_sql(query=revised_query, db=session, receipt_id=out.receipt_id)A tool with a strict return type, such as -> dict, raises AgentXSecurityBlock instead, so catch that.
Name the argument for what it carries (query, sql, command, path, url), so the check reads it.
05Get a free gateway key
The gateway adds more rules and the checks a keyword match can't do, coached recovery, and team review and approval before a risky action runs. Get a free key at agentx-core.com/gateway, with nothing to run. The setup steps come with the key. With a key, blocking is on by default, so handle a block first (step 04), or set AGENTX_POSTURE=audit to keep watching.
06Where next
01Install and wrap a tool
Wrap a tool in one line. Every call it makes is written down on your machine (tool and argument names, no values), and audit prints what your agent did. Nothing is blocked, so your agent runs as it does today.
npm install @agentx-core/security-sdkimport { agentxWatchAll }
from "@agentx-core/security-sdk";
// was: tools: { runSql, sendEmail }
tools: agentxWatchAll({ runSql, sendEmail })Your tools behave exactly as they do today: the wrap watches and records, and blocks nothing. See what it recorded with npx @agentx-core/security-sdk audit
Inventory first? Lists every tool your agent can call, ranked by risk, with no install:
npx @agentx-core/scan .To block TypeScript tools, wrap them with agentxProtect and set AGENTX_API_KEY (and AGENTX_GATEWAY_URL for a gateway that is not on this machine): the gateway checks each call before it runs. If it cannot answer, the call runs unchecked unless AGENTX_FAIL_MODE=closed.
02See what it recorded
Run your agent, then from the folder it runs in:
npx @agentx-core/security-sdk audit # grouped by toolA sample, shortened. Your tools and numbers will differ:
4 calls across 3 tools since 2026-09-14 15:09
4 tools wrapped. 3 called. 1 never ran.
TOOL CALLS SURFACE ARGUMENTS
-----------------------------------------------------------------------
runSql 2 DB limit, sql
refund 1 - amount, currency, order_id
largest amount passed: ≥100,000
sendEmail 1 - body, to
NEW SINCE YOU LAST LOOKED
sendEmail first time we have seen this toolThe record holds tool and argument names, no values. Only wrapped tools appear. Nothing is blocked yet.
03Turn on blocking
To block TypeScript tools, wrap them with agentxProtect and set AGENTX_API_KEY (and AGENTX_GATEWAY_URL for a gateway that is not on this machine): the gateway checks each call before it runs. If it cannot answer, the call runs unchecked unless AGENTX_FAIL_MODE=closed. A blocked action never executes, and your agent gets coaching to recover.
import { agentxProtectAll, isBlock } from "@agentx-core/security-sdk";
// was: tools: agentxWatchAll({ runSql, sendEmail })
tools: agentxProtectAll({ runSql, sendEmail }, { agentId: "billing-bot" })A stopped call comes back as the tool's result, so the model can read why and try again. isBlock(result) tells your code.
Get a free key at agentx-core.com/gateway, with nothing to run. The setup steps come with the key.
04Where next
01Add one line to mcp.json
One line in mcp.json wraps any local server. It catches the dangerous tools/call; turn on blocking and it never reaches the server, and the agent is coached to self-correct, no key.
{
"mcpServers": {
"filesystem": {
"command": "uvx",
"args": [
"agentx-mcp", "npx", "-y",
"@modelcontextprotocol/server-filesystem",
"/data"
]
}
}
}Config uses uvx (no install). Want to watch it block something first?
Trying it on servers you already use? A wrapped server records every call and blocks none of them. AGENTX_POSTURE=enforce in that server's env is how you make it start blocking. Add it per server block; the ones you leave alone keep watching. Read it back with uvx agentx-mcp --audit.
This is keyless and it is your protection for MCP servers today. Gateway-backed Recover over MCP is on the roadmap.
Want the gateway to cover your MCP traffic too?
uvx comes with uv. Without it, install agentx-mcp with pip or pipx.
Claude Code? It writes the entry for you; the command is the same, our proxy first and your server after it:
claude mcp add filesystem -- uvx agentx-mcp npx -y @modelcontextprotocol/server-filesystem /data02See a call stopped
See a DROP TABLE blocked with coaching and a scoped SELECT allowed through, on a stub server of ours:
uvx agentx-mcp --demo # no key, no gateway, no Node, no checkout03See what it recorded
Restart your MCP client and use your agent, then read what the servers you wrapped did. The demo is not on it: it runs in a temporary directory of its own and writes nothing here.
uvx agentx-mcp --audit # grouped by toolA sample, shortened. Your tools and numbers will differ:
TOOL CALLS SURFACE ARGUMENTS
-----------------------------------------------------------------------
fetch_invoice_pdf 1 HTTP url
issue_refund 1 - amount, currency +2 more
largest amount passed: >=1,000
run_sql 1 DB db_session, query
1 call tripped a policy.
1 ran because nothing was blocking at the time.Calls are recorded whether blocking is on or off. Only wrapped tools appear here, so this is not all your agent did.
04Turn on blocking
Every wrapped server records its calls and blocks none of them. To make ONE server block, add this beside args in that server's block, with a comma between them, and repeat it per server you want enforcing:
"env": { "AGENTX_POSTURE": "enforce" }Remove the env line to go back to watching. Every server you did not edit is watching already.
05Where next
The gateway is an HTTP service, so any language can call it. Your tool sends the call to /v1/evaluate before it runs, and acts on the verdict. TypeScript has this as a package (agentxProtect in@agentx-core/security-sdk), and the same thin client is straightforward in any other language.
What you do not get yet is a packaged client for your stack, or a keyless local floor like the Python one. We write that client with you during onboarding.
Which language should we package next?
Or skip the vote and talk to us directly in our Discord and we will wire the gateway into your stack with you.
What you would run
For context, not as a step. The gateway is the service your tools would call, and it is free, hosted by us or run by you. There is no point setting it up until something in your stack calls it, which is the part we do together.
docker compose up -d # what runs once we have wired your clientWhat your tools call over HTTP, whatever language they are written in. Extra rules and the checks a keyword match can't do, coached recovery that finishes the run, and team review before a risky action runs.
Its built-in rules run with no Gemini key. Recover, which writes the safe path and runs the retry for you, comes with our hosted gateway, or with your own Gemini key on a gateway you run. Your language has no check that runs without a gateway yet.