impact-preview MCP server
Provides a safety layer for AI agents by intercepting proposed actions and showing diff previews for human approval before execution.
Also known as agent-polis/impact-preview
- Stars
- 1
- Tools
- β
- Downloads, 30 days
- 162
- Latest version
- 0.2.1
- Last commit
- Feb 13, 2026
- License
- MIT
What is impact-preview MCP?
impact-preview provides a safety layer for AI agents by intercepting proposed actions and showing diff previews for human approval before execution.
Summary generated from the project's README
About impact-preview MCP server
Preventing autonomous AI agents from making destructive changes to your systems is the primary goal of impact-preview. This MCP server acts as a safety layer that intercepts proposed actions, such as file edits or shell commands, and presents a diff preview for human review before anything is actually executed. It functions like a terraform plan for AI, allowing you to see exactly what will change, including risk assessments for high-stakes operations like modifying production databases or system files.
Developers can use this server locally with Claude Desktop or Cursor by configuring the MCP settings to point to the local server URL. The system provides specific tools like preview_file_write, preview_file_delete, and preview_shell_command to facilitate this oversight. For more advanced setups, a Streamlit dashboard is available to manage the approval workflow, and a Python SDK allows you to wrap agent code with a decorator that blocks execution until a human provides authorization. This setup ensures that every action leaves an audit trail for governance and security.
What you can do with it
- 1Reviewing file modificationsAsk your AI client to show a diff of a configuration file change before it is applied.
- 2Preventing accidental deletionsUse the server to see exactly what data will be lost before an agent deletes a file.
- 3Mitigating dangerous shell commandsFlag and inspect potentially harmful terminal commands before they run on your system.
- 4Assessing path securityPerform a quick check to see if a specific file path carries high operational risk.
Written from the project's README. Every use case is checked against a quote from it.
How to install impact-preview MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall impact-preview MCP in Claude Code
$ claude mcp add impact-preview -- uvx impact-previewInstall impact-preview MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"impact-preview": {
"command": "uvx",
"args": [
"impact-preview"
]
}
}
}Install impact-preview MCP in VS Code
.vscode/mcp.json
{
"servers": {
"impact-preview": {
"type": "stdio",
"command": "uvx",
"args": [
"impact-preview"
]
}
}
}Install impact-preview MCP in VS Code CLI
$ code --add-mcp '{"name":"impact-preview","type":"stdio","command":"uvx","args":["impact-preview"]}'Install impact-preview MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"impact-preview": {
"command": "uvx",
"args": [
"impact-preview"
]
}
}
}Install impact-preview MCP in Codex
$ codex mcp add impact-preview -- uvx impact-previewInstall impact-preview MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.impact-preview] command = "uvx" args = ["impact-preview"]
Install impact-preview MCP in Gemini CLI
$ gemini mcp add -s user impact-preview uvx -- impact-previewInstall impact-preview MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"impact-preview": {
"command": "uvx",
"args": [
"impact-preview"
]
}
}
}Configuration
DATABASE_URLFREE_TIER_ACTIONS_PER_MONTHLOG_LEVELREDIS_URLSECRET_KEY
| Name | Description | |
|---|---|---|
| DATABASE_URL | β | |
| FREE_TIER_ACTIONS_PER_MONTH | β | |
| LOG_LEVEL | β | |
| REDIS_URL | β | |
| SECRET_KEY | β |
Automated checks
Ran Nov 15, 2026Full report βNot verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work Β· What to fix for more points
- Source repository linked and reachableagent-polis/impact-preview is public and reachablegithub.com/agent-polis/impact-preview βPass
- Package names this repository as its sourceimpact-preview names https://github.com/agent-polis/Leviathan#readme as its sourcepypi.org/project/impact-preview/ βFinding
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html βPass
- Commit or release in the last yearLast commit or release 2026-02-13github.com/agent-polis/impact-preview βPass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from impact-previewPass
- No critical advisory in the package or its dependenciesCritical advisory: GHSA-3qf3-8w2g-rqmxosv.dev/vulnerability/GHSA-3qf3-8w2g-rqmx βFinding
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubπ Agent Polis
Impact Preview for AI Agents - "Terraform plan" for autonomous AI actions
See exactly what will change before any AI agent action executes.
Agent Polis intercepts proposed actions from autonomous AI agents, analyzes their impact, shows you a diff preview of what will change, and only executes after human approval. Stop worrying about your AI agent deleting your production database.
π― The Problem
Autonomous AI agents are powerful but dangerous. Recent incidents:
- Replit Agent deleted a production database, then lied about it
- Cursor YOLO mode deleted an entire system including itself
- Claude Code learned to bypass safety restrictions via shell scripts
Developers want to use AI agents but don't trust them. Current solutions show what agents want to do, not what will happen. There's no "terraform plan" equivalent for AI agent actions.
π The Solution
AI Agent proposes action β Agent Polis analyzes impact β Human reviews diff β Approve/Reject β Execute
# Example: Agent wants to write to config.yaml
- database_url: postgresql://localhost:5432/dev
+ database_url: postgresql://prod-server:5432/production
! WARNING: Production database URL detected (CRITICAL RISK)
β¨ Features
- Impact Preview: See file diffs, risk assessment, and warnings before execution
- Approval Workflow: Approve, reject, or modify proposed actions
- Risk Assessment: Automatic detection of high-risk operations (production data, system files, etc.)
- Audit Trail: Event-sourced log of every proposed and executed action
- SDK Integration: Easy
@require_approvaldecorator for your agent code - Dashboard: Streamlit UI for reviewing and approving actions
π Quick Start (2 minutes)
The fastest way to try Agent Polis is the MCP server with Claude Desktop or Cursor.
1. Install & Run
pip install impact-preview
impact-preview-mcp
2. Configure Claude Desktop
Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"impact-preview": {
"url": "http://localhost:8000/mcp"
}
}
}
3. Try It
Ask Claude to edit a file - it now has these tools:
| Tool | What it does |
|---|---|
preview_file_write |
Shows diff before any edit |
preview_file_delete |
Shows what will be lost |
preview_shell_command |
Flags dangerous commands |
check_path_risk |
Quick risk check for any path |
Example prompt:
"Preview what would happen if you changed the database URL in config.yaml to point to production"
Claude will show you the diff and risk assessment before making changes.
π¦ Full Server Installation
For the complete approval workflow with dashboard and API:
# Using Docker (recommended)
docker-compose up -d
# Or locally
pip install impact-preview
impact-preview
Register an Agent
curl -X POST http://localhost:8000/api/v1/agents/register \
-H "Content-Type: application/json" \
-d '{"name": "my-agent", "description": "My AI coding assistant"}'
Submit Action β Review β Approve
# Submit
curl -X POST http://localhost:8000/api/v1/actions \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action_type": "file_write", "target": "/app/config.yaml", "description": "Update DB URL", "payload": {"content": "db: prod"}}'
# Preview
curl http://localhost:8000/api/v1/actions/ACTION_ID/preview -H "X-API-Key: YOUR_API_KEY"
# Approve (or reject)
curl -X POST http://localhost:8000/api/v1/actions/ACTION_ID/approve -H "X-API-Key: YOUR_API_KEY"
Audit Trail (Events)
You can retrieve the complete audit trail for an action:
curl http://localhost:8000/api/v1/actions/ACTION_ID/events -H "X-API-Key: YOUR_API_KEY"
ActionPreviewGenerated event payload includes machine-readable governance context:
data.governance.policy.decision/data.governance.policy.matched_rule_iddata.governance.scanner.reason_ids/data.governance.scanner.max_severity
π SDK Integration
Wrap your agent's dangerous operations:
from agent_polis import AgentPolisClient
client = AgentPolisClient(api_url="http://localhost:8000", api_key="YOUR_KEY")
# Decorator approach - blocks until human approves
@client.require_approval(action_type="file_write")
def write_config(path: str, content: str):
with open(path, 'w') as f:
f.write(content)
# This will: submit β wait for approval β execute only if approved
write_config("/etc/myapp/config.yaml", "new content")
π₯οΈ Dashboard
Launch the Streamlit dashboard to review pending actions:
pip install impact-preview[ui]
streamlit run src/agent_polis/ui/app.py
π API Reference
Actions API
| Endpoint | Method | Description |
|---|---|---|
/api/v1/actions |
POST | Submit action for approval |
/api/v1/actions |
GET | List your actions |
/api/v1/actions/pending |
GET | List pending approvals |
/api/v1/actions/{id} |
GET | Get action details |
/api/v1/actions/{id}/preview |
GET | Get impact preview |
/api/v1/actions/{id}/diff |
GET | Get diff output |
/api/v1/actions/{id}/approve |
POST | Approve action |
/api/v1/actions/{id}/reject |
POST | Reject action |
/api/v1/actions/{id}/execute |
POST | Execute approved action |
Action Types
file_write- Write content to a filefile_create- Create a new filefile_delete- Delete a filefile_move- Move/rename a filedb_query- Execute a database query (read)db_execute- Execute a database statement (write)api_call- Make an HTTP requestshell_command- Run a shell commandcustom- Custom action type
Risk Levels
- Low: Read operations, safe changes
- Medium: Write operations to non-critical files
- High: Delete operations, system files
- Critical: Production data, irreversible changes
π§ Configuration
# .env
SECRET_KEY=your-secret-key
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/agent_polis
REDIS_URL=redis://localhost:6379/0
# Optional
FREE_TIER_ACTIONS_PER_MONTH=100
LOG_LEVEL=INFO
πΊοΈ Roadmap
| Version | Focus | Status |
|---|---|---|
| v0.2.0 | File operation preview | Current |
| v0.3.0 | Database operation preview | Planned |
| v0.4.0 | API call preview | Planned |
| v0.5.0 | IDE integrations (Cursor, VS Code) | Planned |
| v1.0.0 | Production ready | Planned |
π€ Contributing
git clone https://github.com/agent-polis/impact-preview.git
cd impact-preview
pip install -e .[dev]
pre-commit install
pytest
π License
MIT License - see LICENSE for details.
Built for developers who want AI agents they can actually trust.
impact-preview MCP questions
How do I add impact-preview MCP to Claude Code?
Run claude mcp add impact-preview -- uvx impact-preview in your terminal. Add --scope user to make it available in every project.
How do I add impact-preview MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What does impact-preview do?
It intercepts proposed actions from autonomous AI agents, analyzes their impact, shows a diff preview, and only executes after human approval.
How can I use this with Claude Desktop?
You can install it via pip and add the MCP server configuration to your Claude Desktop config file.