QUICKSTART

FROM ZERO TO SCANNING IN 30 SECONDS

No account required to get started. Run the MCP Scanner against your configuration, review your grade, then optionally connect to Shield to track results over time and deploy alarms.

// 001

STEP 1: RUN THE SCANNER

Run the MCP Scanner directly with npx. No installation needed. It reads your MCP configuration automatically from the standard locations used by Claude Desktop, VS Code, and Cursor.

$ npx @agentdefenders/mcp-scan

The scanner runs locally. No data leaves your machine unless you explicitly pass an API key. Results appear in your terminal within seconds.

PREREQUISITES

>Node.js 18 or later (node --version to check)
>npx ships with npm (included with Node.js). No separate install needed.
>At least one MCP client configured (Claude Desktop, VS Code, or Cursor)

TROUBLESHOOTING

!command not found: npx -- Install Node.js 18+ from nodejs.org or via your package manager.
!permission denied -- Do not use sudo. Fix npm permissions: npm config set prefix ~/.npm-global
!no MCP configuration found -- The scanner checks standard locations. Verify your MCP client is configured, or pass a custom path with --config-path.

// 002

STEP 2: UNDERSTAND YOUR GRADE

The scanner assigns your MCP configuration a letter grade based on the highest severity finding across all analyzers. Use the grade to triage immediately and share a single signal with your team.

CLEAN

No findings. Your MCP configuration passed all analyzer checks.

LOW RISK

One or more low-severity findings. Review the output and address items when possible.

MODERATE RISK

Medium-severity findings present. At least one MCP server or tool has behavior that warrants attention.

HIGH RISK

High-severity findings. One or more servers show patterns consistent with tool poisoning or prompt injection.

CRITICAL

Critical findings. Immediate action required. Stop using the flagged MCP servers until they are reviewed.

// 003

STEP 3: SIGN UP AND UPLOAD

Create a free Shield account to persist scan results, track your grade over time, and get notified if a previously clean configuration changes. Pass your API key to the scanner and results upload automatically.

$ npx @agentdefenders/mcp-scan --api-key YOUR_KEY

Replace YOUR_KEY with the API key from your Shield dashboard. Find it under Settings → API Keys.

CREATE FREE ACCOUNT

// 004

STEP 4: DEPLOY YOUR FIRST ALARM

Shield Alarms are deception-based tripwires. Each alarm looks indistinguishable from a real credential, file, or service. If anything accesses it, you get an instant alert. There are no false positives -- every trigger is unauthorized access.

OPEN THE DASHBOARD

Navigate to Shield Alarms in the app dashboard.

CHOOSE AN ALARM TYPE

Select from API keys, wallets, database credentials, env files, ports, SSH keys, or MCP tools.

DEPLOY AND MONITOR

Follow the setup instructions for your chosen alarm type. Alerts arrive via email, Slack, or webhook.

New to Shield Alarms? Read the alarms documentation →

// 005

STEP 5: TEST YOUR ALARM

After deploying an alarm, verify the notification pipeline works end-to-end. Use the test trigger button in the dashboard, or send a manual trigger via the API:

$ curl -X POST https://api.agentdefenders.ai/api/v1/detect/trigger \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"alarm_id": "YOUR_ALARM_ID", "test": true}'

Test triggers are flagged as is_test: true in the dashboard so they do not pollute your real detection history. Verify you receive the alert on your configured channel (email, Slack, etc.) within a few seconds.

MCP SCANNER REFERENCE SHIELD ALARMS REFERENCE

$ curl -X POST https://api.agentdefenders.ai/api/v1/detect/trigger \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"alarm_id": "YOUR_ALARM_ID", "test": true}'