Identifies transitive excessive agency in multi-agent orchestration graphs by detecting indirect paths to dangerous tools.
Also known as GuardBee/guardbee-mcp, @guardbee/mcp-agent-graph-auditor
- Stars
- 2
- Tools
- 4
- Downloads, 30 days
- 1,921
- Latest version
- 0.1.2
- Last commit
- Nov 12, 2026
- License
- MIT
What is agent-graph-auditor MCP?
agent-graph-auditor identifies transitive excessive agency in multi-agent orchestration graphs by detecting indirect paths to dangerous tools. It exposes 4 tools, such as scan_text, scan_file, scan_directory.
Summary generated from the project's README
About agent-graph-auditor MCP server
Securing multi-agent orchestration by identifying hidden paths to dangerous tools is the primary function of agent-graph-auditor. It detects transitive excessive agency, which occurs when an agent can reach a sensitive capability like shell access or filesystem writes through a second agent via delegation or group chat. This tool is designed for developers building complex agentic workflows using Python frameworks.
Users can run this server locally through Claude Desktop or integrate it into CI/CD pipelines using the command line. It supports LangGraph, CrewAI, and AutoGen/ag2 by extracting relationships from source code. While LangGraph analysis is structural, the server uses heuristics to infer delegation for CrewAI and AutoGen. The server provides tools to scan individual Python files, specific text snippets, or entire directories to find direct or multi-hop security risks.
Findings are categorized by severity and can be exported in SARIF 2.1.0 format for compatibility with GitHub Code Scanning. The system uses a name-based capability catalog to classify tools into categories such as code execution, network access, and credential access.
What you can do with it
- 1Detecting indirect tool accessIdentify if a researcher agent can reach a shell tool by delegating tasks to an operations agent.
- 2Auditing multi-agent frameworksScan Python source code to map agent relationships in LangGraph, CrewAI, or AutoGen.
- 3Automating security in CI/CDRun a directory scan that fails the build if high-severity transitive agency is discovered.
- 4Reviewing dangerous tool capabilitiesList all tool patterns that the auditor considers dangerous across different categories.
Written from the project's README. Every use case is checked against a quote from it.
How to install agent-graph-auditor MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall agent-graph-auditor MCP in Claude Code
$ claude mcp add agent-graph-auditor -- npx -y @guardbee/mcp-agent-graph-auditorInstall agent-graph-auditor MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"agent-graph-auditor": {
"command": "npx",
"args": [
"-y",
"@guardbee/mcp-agent-graph-auditor"
]
}
}
}Install agent-graph-auditor MCP in VS Code
.vscode/mcp.json
{
"servers": {
"agent-graph-auditor": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@guardbee/mcp-agent-graph-auditor"
]
}
}
}Install agent-graph-auditor MCP in VS Code CLI
$ code --add-mcp '{"name":"agent-graph-auditor","type":"stdio","command":"npx","args":["-y","@guardbee/mcp-agent-graph-auditor"]}'Install agent-graph-auditor MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"agent-graph-auditor": {
"command": "npx",
"args": [
"-y",
"@guardbee/mcp-agent-graph-auditor"
]
}
}
}Install agent-graph-auditor MCP in Codex
$ codex mcp add agent-graph-auditor -- npx -y @guardbee/mcp-agent-graph-auditorInstall agent-graph-auditor MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.agent-graph-auditor] command = "npx" args = ["-y", "@guardbee/mcp-agent-graph-auditor"]
Install agent-graph-auditor MCP in Gemini CLI
$ gemini mcp add -s user agent-graph-auditor npx -- -y @guardbee/mcp-agent-graph-auditorInstall agent-graph-auditor MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"agent-graph-auditor": {
"command": "npx",
"args": [
"-y",
"@guardbee/mcp-agent-graph-auditor"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @guardbee/mcp-agent-graph-auditor 0.1.2 in an isolated container with no network and no keys. It answered and listed 4 tools.
agent-graph-auditor MCP tools 4
Read from the server with tools/listscan_textScan a Python snippet defining a multi-agent orchestration (LangGraph, CrewAI, or AutoGen/ag2) for excessive agency reachable through delegation or group membership — an agent with no dangerous tool of its own that can still reach one (shell/code-exec/file-write/network/credentials) through another agent it can hand off to.
scan_fileScan a single Python file for excessive-agency paths across LangGraph/CrewAI/AutoGen orchestration constructs
scan_directoryRecursively scan a directory of Python files and report excessive-agency paths found in each. Each file's agent/tool graph is analyzed independently — variable references don't resolve across files, so a Crew/GroupChat whose members are defined in a different file than the assembling call won't be connected.
list_patternsList every dangerous-capability rule this auditor looks for at the end of a delegation path, grouped by category
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHub@guardbee/mcp-agent-graph-auditor
🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇩🇪 Deutsch
An MCP (Model Context Protocol) server that builds a reachability graph across a multi-agent orchestration and finds transitive excessive agency — an agent that was never directly given a dangerous tool, but can still reach one through another agent it's allowed to delegate to.
mcp-server-auditor catches an MCP server whose own tool grants shell/eval/SQL access directly. ai-code-scanner catches a single agent's tool list containing execute_command. Both of those are one hop: agent → tool. Multi-agent frameworks add a second kind of edge — delegation, group chat, function-execution routing — and a "safe-looking" agent with only a web_search tool can become dangerous the moment it's allowed to hand work off to a coworker that holds a shell tool. That two-hop path is invisible to a scanner that only looks at one agent's own tool list at a time.
Telemetry is off by default. With
GUARDBEE_TELEMETRY=1it sends the server, tool, success, duration and short parameter values such as a file path; longer strings and fields likecontent,tokenorpasswordare replaced with a placeholder. See@guardbee/mcp-telemetry.
Claude ──► agent-graph-auditor ──► Your multi-agent Python source
│
├─ LangGraph (add_node/add_edge — structural, read directly from the graph API)
├─ CrewAI (Agent/tools/allow_delegation + Crew membership — heuristic)
└─ AutoGen/ag2 (GroupChat membership, code_execution_config, register_function — heuristic)
How the graph is built
- Extract. Framework-specific regex extractors pull agent/tool nodes and relationship edges out of the source:
has_tool(an agent's own toolset),delegates_to(CrewAIallow_delegation, LangGraphadd_edge),group_member(AutoGenGroupChatco-membership — any member's output can be routed to any other by the manager),executes_via(AutoGenregister_function's caller/executor split). - Classify. Every tool node is checked against a name-based capability catalog (code execution, process execution, filesystem write, network, credentials access) — the same kind of heuristic
ai-code-scanner's excessive-agency pattern uses, just applied to a graph of tools instead of one server's tool list. - Reach. A breadth-first search runs from every agent node. A capability tool reached via a straight
has_tooledge is a direct finding (still reported — useful even without a second agent in the picture). A capability tool reached only after crossing at least onedelegates_to/group_member/executes_viaedge is transitive — the finding this package exists for — and is always reported as critical, regardless of the tool's own base severity, because the agent holding it was never audited for it directly.
LangGraph is the most reliable target: add_node/add_edge calls are the orchestration graph in the source, no inference needed. CrewAI and AutoGen require inferring delegation from framework semantics (allow_delegation, GroupChat membership) rather than an explicit edge in the code, so treat those as heuristic — see Limitations below.
Features
- 3 frameworks: LangGraph (structural), CrewAI (heuristic), AutoGen/ag2 (heuristic)
- 7 capability rules across 5 categories (code-execution, process-execution, filesystem-write, network, credentials-access)
- Distinguishes direct (single-agent) from transitive (delegation-crossing) excessive agency — the transitive case is what no single-agent scanner in this monorepo catches
- Multi-hop aware — a 3+ agent delegation chain is found the same way a 2-agent one is
- SARIF 2.1.0 output — CI/CD integration (GitHub Code Scanning, etc.)
- Config file support via
guardbee.yml - 31 unit tests, plus end-to-end verification against realistic fixtures for all three frameworks
Quick Start
Claude Desktop / MCP Client
{
"mcpServers": {
"guardbee-agent-graph-auditor": {
"command": "npx",
"args": ["-y", "@guardbee/mcp-agent-graph-auditor"]
}
}
}
CLI (CI/CD)
npx @guardbee/mcp-agent-graph-auditor scan ./agents --fail-on=high --format=sarif > results.sarif
MCP Tools
| Tool | Description |
|---|---|
scan_text |
Scans a Python snippet |
scan_file |
Scans a single .py file |
scan_directory |
Recursively scans a directory of .py files |
list_patterns |
Lists the dangerous-capability catalog by category |
Example
researcher = Agent(role="Researcher", tools=[web_search_tool], allow_delegation=True)
ops = Agent(role="Ops Engineer", tools=[shell_tool], allow_delegation=False)
writer = Agent(role="Writer", tools=[], allow_delegation=False)
crew = Crew(agents=[researcher, ops, writer], tasks=[])
researcher never holds shell_tool — but allow_delegation=True plus co-membership in the same Crew as ops means it can hand work off to an agent that does. This scanner reports:
🔴 CRITICAL Transitive excessive agency: reaches shell_tool
Path: Researcher → Ops Engineer → shell_tool
🔴 CRITICAL Direct excessive agency: reaches shell_tool
Path: Ops Engineer → shell_tool
writer — no tools, no delegation — gets no finding at all.
Configuration (guardbee.yml)
agent-graph-auditor:
fail-on: high # any | critical | high | medium | none
max-files: 2000
exclude:
- ".test.py"
Limitations (by design)
- Single-file scope. Each file's graph is extracted independently — Python variable references don't resolve across files. A
Crew(agents=[researcher, ops])call will only connect toAgent(...)definitions found in the same file, even when scanning a whole directory. - CrewAI/AutoGen extraction is heuristic, not a real Python parser — constructor bodies are captured with a bounded text window rather than exact paren-matching (the same tradeoff
ai-code-scanner's pattern-window matching makes), and it doesn't track reassignment, conditional agent construction, or dynamically built tool lists. - AutoGen's
speaker_selection_methodisn't modeled —GroupChatco-membership is always treated as a bidirectional reachability edge, which is the conservative (over-inclusive, not under-inclusive) assumption. - Capability classification is name-based. A tool named
search_toolthat secretly shells out internally won't be flagged; a tool namedshell_tool_disabledwill be. Review findings; don't take them as ground truth. - Only Python source is scanned in v1 — LangChain/LangGraph's JS/TS API isn't covered yet.
Development
npm run build
npm test # 31 unit tests
License
MIT — GuardBee
Feedback
Questions, ideas, or a false positive? Start a thread in GitHub Discussions or open an issue. If GuardBee is useful to you, a ⭐ on the repository helps others find it.
agent-graph-auditor MCP questions
How do I add agent-graph-auditor MCP to Claude Code?
Run claude mcp add agent-graph-auditor -- npx -y @guardbee/mcp-agent-graph-auditor in your terminal. Add --scope user to make it available in every project.
How do I add agent-graph-auditor MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does agent-graph-auditor MCP provide?
It exposes 4 tools, including scan_text, scan_file, scan_directory, list_patterns.
How does it handle telemetry?
Telemetry is disabled by default; you can enable it using the GUARDBEE_TELEMETRY=1 environment variable.
Can it scan across multiple files?
No, the scanner has a single-file scope where each file's graph is extracted independently, meaning variable references do not resolve across files.
What kind of output does it provide?
The server provides SARIF 2.1.0 output, which allows for integration with CI/CD tools like GitHub Code Scanning.