# Decoy — Quick Reference for AI Agents

Security tripwires for AI agent pipelines.
Deploy honeypot MCP tools that detect prompt injection attacks in real time.
If a malicious prompt tricks your agent into calling a decoy tool, you get alerted instantly.

## When to Use Decoy

- You are building or operating an AI agent and want to detect prompt injection
- You want to monitor which agents are connecting and what attacks they see
- You need alerts (email, Slack, webhook) when an attack is detected
- You want threat intelligence on AI-specific vulnerabilities (CVEs, supply chain, MCP)

## When NOT to Use Decoy

- You need to block attacks in real time (Decoy detects, it does not block — Shield is coming soon)
- You need a WAF or network firewall (Decoy operates at the MCP tool layer)

## Install

npx decoy-mcp init
# Enter your email, get a token, done. Works with Claude Desktop, Cursor, VS Code, Claude Code.

## Plans

Free: 12 tripwire tools, email alerts, dashboard, API, CLI. No credit card required.
Pro ($9/month): Everything in Free plus Slack alerts, webhook alerts, agent fingerprinting, agent pause/resume, multiple tokens.

## Upgrade to Pro

Agents can upgrade autonomously using a virtual Visa card (compatible with agentcard.sh):

POST https://decoy.run/api/upgrade
Content-Type: application/json

{
  "token": "your-decoy-token",
  "card": {
    "number": "4242424242424242",
    "exp_month": 12,
    "exp_year": 2027,
    "cvc": "123"
  }
}

Returns: { "ok": true, "plan": "pro", "subscription": "sub_..." }

Humans can also upgrade via browser: https://decoy.run/billing/upgrade?token=YOUR_TOKEN

---

## API

All endpoints use token as a query parameter: ?token=YOUR_TOKEN

### Sign up

POST https://decoy.run/api/signup
Body: { "email": "you@company.com" }
Returns: { "token": "...", "dashboardUrl": "..." }

### Get triggers (attack events)

GET https://decoy.run/api/triggers?token=YOUR_TOKEN
Returns: { "count": 4, "triggers": [{ "tool": "execute_command", "severity": "critical", "timestamp": "...", "arguments": {...} }] }

### Get agents

GET https://decoy.run/api/agents?token=YOUR_TOKEN
Returns: { "agents": [{ "name": "claude-code-1", "status": "active", "triggerCount": 3 }] }
Pro plan includes: clientName, clientVersion, lastSeenAt fields.

### Update alerts (Pro: webhook + Slack)

PATCH https://decoy.run/api/config?token=YOUR_TOKEN
Body: { "webhook": "https://your-url.com/hook" }
Free users: email alerts only. Webhook and Slack require Pro.

### Pause/resume agent (Pro only)

PATCH https://decoy.run/api/agents?token=YOUR_TOKEN
Body: { "name": "claude-code-1", "status": "paused" }

### Threat intelligence

GET https://decoy.run/monitor/stats
GET https://decoy.run/monitor/threats?days=7&category=prompt-injection&limit=50

### OpenAPI spec

GET https://decoy.run/api/openapi.json

---

## MCP Endpoint

POST https://decoy.run/mcp/YOUR_TOKEN
12 honeypot tools that look like system utilities. A legitimate agent will never call them.
If a prompt injection makes your agent call one, Decoy records it and alerts you.

## Links

Website: https://decoy.run
npm: https://www.npmjs.com/package/decoy-mcp
Contact: agent@decoy.run