AgentShield MCP: Human vs Agent Risk Router

AgentShield MCP is a demo that explores how modern systems can detect whether an incoming request is from a human user, an automated bot, or an AI agent, and then route or adapt behavior based on risk and context.

It integrates multiple MCP-style tools to simulate real-world risk signals—geo, device, and velocity—and applies a policy engine to produce clear, explainable outcomes.

---

Features

This repository includes two ways to run AgentShield:

• Interactive Streamlit Simulator: A rich web UI for exploring different risk scenarios and visualizing the policy engine's decisions in real-time.
• MCP Server: A protocol-correct MCP server that exposes the risk tools for programmatic use by AI agents and other clients.

---

Quickstart Guide (for the Web Simulator)

This guide will help you get the interactive web simulator running on your local machine in just a few steps.

Step 1: Install the necessary software

First, you need to install all the Python packages the application depends on. Open your terminal and run this command:

pip install -r requirements.txt

This command reads the requirements.txt file and downloads the required libraries.

Step 2: Start the application

Next, start the application's backend and frontend servers. Run this command in your terminal:

make dev

This command does two things at once: it starts the backend API server and the frontend web interface. You will see a lot of output in your terminal as the servers start up.

Step 3: Open the web simulator

Once the servers are running, your terminal will display a message like: You can now view your Streamlit app in your browser.

Open the "Local URL" (it usually looks like http://localhost:8501) in your web browser to start using the AgentShield MCP simulator.

---

MCP Server

For programmatic access, AgentShield provides an MCP server that exposes the core logic as tools.

Quick Start: MCP Server

To run the MCP server over stdio:

make mcp

Alternatively, you can run the server directly:

python agentshield_mcp/server.py

Connecting with Claude Desktop

You can connect to the MCP server from clients like Claude Desktop. Here is an example config.json snippet to connect to the local stdio server:

{
  "tools": {
    "my_agentshield_tools": {
      "type": "stdio",
      "command": ["python", "agentshield_mcp/server.py"]
    }
  }
}

---

Problem

AI and automation are transforming the way users and systems interact, but most architectures still treat every request the same. Real-world systems need to:

• Distinguish between humans, scripts, and AI agents
• Read device and network signals for anomalies
• Adjust data visibility and access dynamically
• Apply transparent, explainable policies

AgentShield MCP is a small, hands-on prototype showing how these ideas can be implemented in practice.

---

Concept

Each request flows through a series of modular tools:

1. IP / Geo Risk Tool (mock)
2. Device Fingerprint Tool (mock)
3. Velocity / Anomaly Tool (mock)
4. Policy Engine

Each output includes reasoning and raw signals to make the decision process explainable.

---

Tech Stack

• Frontend: Streamlit
• Backend: FastAPI
• Language: Python
• MCP Server: FastMCP
• Testing: Pytest