Agentward

What agentward-ai/agentward MCP server does

The agentward-ai/agentward MCP server acts as a security control point for AI agent tool use. It sits between an agent and connected tools, then evaluates each tool call against declarative YAML policy rules. The stated goal is least-privilege enforcement at runtime rather than relying on instructions placed in the model context.

The project is categorized under 🔒 Security and is intended for environments where agents can access files, APIs, email, calendars, databases, shells, or other capabilities. It can classify sensitive information, including PII and PHI, identify dangerous combinations of tools or actions, and create compliance audit trails. The material also describes scanning and policy-generation workflows for existing MCP configurations and Python tool definitions.

How it works

AgentWard operates as a proxy between the client-side agent and its tools. Every tools/call request can be checked against a YAML policy before the underlying operation runs. Rules can allow, block, or require approval for actions, and can constrain arguments such as file paths. Enforcement occurs in application code outside the LLM context, so changing the prompt does not change the policy.

The project describes a lifecycle of scanning, configuring, enforcing, verifying, and monitoring. Scanning can discover MCP configurations for supported agent environments, inspect Python tool definitions, classify risks, and detect patterns such as interpreter-plus-stdin chains, write-then-reconfigure persistence chains, and URL parameters without allowlists. Monitoring can produce JSON Lines audit output and RFC 5424 syslog output for SIEM use.

The proxy supports both stdio and HTTP modes. The repository also describes checks for supply-chain risks in skill directories, including unsafe deserialization, YAML loading patterns, executable installation hooks, dependency names, and Python .pth files.

Setup and configuration

The documented starting point is Python 3.11 or newer, followed by installation from PyPI:

pip install agentward
agentward init

The init command scans available tools, presents a risk summary, generates a recommended policy, and wires the proxy into the environment. Individual stages can also be run separately. agentward scan accepts a project, skill directory, MCP configuration, or other path. agentward configure generates an agentward.yaml file with security-aware defaults based on scan results.

Policies use YAML and can define a default action, per-skill and per-tool actions, approval requirements, and argument constraints. The repository shows path restrictions such as required prefixes, prohibited path traversal, and blocklisted sensitive paths. The exact policy needed depends on the tools and agent environment being protected.

Tools and capabilities

The listed MCP tools provide filesystem operations within allowed directories:

• Read text, media, or multiple files; read_file is deprecated in favor of read_text_file.
• Create, overwrite, edit, move, and rename files or directories.
• List directories, include file sizes, or return a recursive directory tree.
• Search for files and directories with glob-style patterns.
• Retrieve file or directory metadata.
• List the directories available to the server.

The agentward-ai/agentward MCP server restricts these operations to configured allowed directories. Text reads support head and tail limits, while media reads return base64 content with a MIME type.

Limitations and notes

The provided material does not specify a complete configuration reference, HTTP deployment procedure, or approval UI. It also does not identify every supported MCP client beyond the environments named in the repository, which include Claude Desktop, Cursor, Windsurf, and VS Code. The read_file operation remains listed but is explicitly deprecated.

The project is source-available under the Business Source License 1.1. Review the repository license and policy behavior before deploying it in a production environment. The agentward-ai/agentward MCP server governs calls routed through its proxy; the supplied material does not claim that it automatically controls tools bypassing that proxy.