@perfai/mcp

A Model Context Protocol (MCP) server that brings PerfAI Security, Design & Quality Analysis directly into your AI coding assistant. Authenticate once, then list and triage API security issues, generate AI-powered fix prompts, and view detailed dashboards — all from within Claude, Cursor, VS Code, Windsurf, Zed, or any MCP-compatible client.

⚡ Setup

Run the setup wizard — it auto-detects your MCP clients (Claude, Cursor, VS Code, Windsurf, Zed) and writes the correct config for each:

npx -y --package=@perfai/mcp@latest perfai-mcp-setup

That's it. No config file editing needed.

🔐 Authentication

Run the login tool from your AI assistant to open a browser-based Auth0 login. After authenticating, all protected tools become available automatically.

login                  # opens browser → authenticate → done
auth_status            # verify you're authenticated
logout                 # clear session

🛠️ Available Tools

🔓 Public (no authentication required)

| Tool | Description | | ------------- | -------------------------------------------------------- | | login | Authenticate with PerfAI via Auth0 OAuth. Opens browser. | | auth_status | Check current authentication status and user info. |

🔒 Protected (authentication required)

User & Session

| Tool | Description | | ----------- | ------------------------------------------------------ | | user_info | Get detailed information about the authenticated user. | | logout | Clear authentication session. | | setup | Auto-configure org and app with default values. |

Organization & App Management

| Tool | Parameters | Description | | ---------------------- | ---------------------------------------------------- | ------------------------------------------------------------------ | | manage_organizations | action (list/select/refresh), sequence, org_id | List orgs with sequence numbers, select by number or ID. | | list_apps | search, environment, page, limit | List all APPs with optional filters and pagination. | | select_app | sequence, name_or_label, app_id | Select an APP by sequence number, partial name/label, or exact ID. |

Issue Summary

| Tool | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | summarize_issues | Full dashboard for the selected APP — security risk, design issues, quality issues, attack surface, bug bounty savings, and coverage. |

Security Issues

| Tool | Parameters | Description | | ----------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------- | | show_security_issues | limit, severities[], status, sort_by, sort_order, search, cursor | List security vulnerabilities with filters. | | ai_fix_security_issue | issue_id (sequence #, ID, or description) | Generate an AI-powered fix prompt for a security issue. | | check_security_fixes | wait_seconds | Check which previously fixed issues were actually resolved. |

Design Issues

| Tool | Parameters | Description | | --------------------- | -------------------------------------------------------------- | ----------------------------------------------------- | | show_design_issues | limit, status, sort_by, sort_order, search, cursor | List API design issues with filters. | | ai_fix_design_issue | issue_id | Generate an AI-powered fix prompt for a design issue. | | check_design_fixes | wait_seconds | Check which design fixes were actually resolved. |

Quality / Spec Validation Issues

| Tool | Parameters | Description | | ---------------------- | ---------------------------------------------------- | ------------------------------------------------------ | | show_quality_issues | limit, sort_by, sort_order, search, cursor | List spec validation issues. | | ai_fix_quality_issue | issue_id | Generate an AI-powered fix prompt for a quality issue. | | check_quality_fixes | wait_seconds | Check which quality fixes were actually resolved. |

Session State

| Tool | Description | | ------------------- | -------------------------------------------------- | | show_fixed_issues | Show all AI-fixed issues from the current session. |

💡 Typical Workflow

1. login                                                          # authenticate
2. manage_organizations {"action": "list"}                        # see your orgs
3. manage_organizations {"action": "select", "sequence": 1}
4. list_apps {"search": "payments"}                               # find your app
5. select_app {"sequence": 2}                                     # or by name: {"name_or_label": "payments"}
6. summarize_issues                                               # dashboard overview
7. show_security_issues {"severities": ["Critical", "High"]}
8. ai_fix_security_issue {"issue_id": "3"}                        # fix issue #3
9. show_design_issues {"status": "Open"}
10. show_quality_issues {}

📋 Tool Examples

Organization & App Selection

// List organizations with sequence numbers
manage_organizations {"action": "list"}

// Select org by sequence number (preferred)
manage_organizations {"action": "select", "sequence": 2}

// List apps — filter by name or environment
list_apps {"search": "checkout", "environment": "production", "page": 1, "limit": 50}

// Select app by partial name
select_app {"name_or_label": "checkout"}

// Select app by sequence number from list_apps
select_app {"sequence": 4}

Summary Dashboard

// Full dashboard: security + design + quality + attack surface
summarize_issues {}

Security Issues

// Show only Critical and High issues
show_security_issues {"severities": ["Critical", "High"], "limit": 20}

// Show dismissed issues
show_security_issues {"status": "Dismissed"}

// Fix issue #5
ai_fix_security_issue {"issue_id": "5"}

// Fix by description
ai_fix_security_issue {"issue_id": "System Design Issues/Enumerable Resource ID • GET /users"}

Design & Quality Issues

show_design_issues {"status": "Open", "sort_by": "createdOn", "sort_order": "DESC"}
show_quality_issues {"limit": 50}
ai_fix_design_issue {"issue_id": "2"}
ai_fix_quality_issue {"issue_id": "7"}

🚀 Local Development

git clone https://github.com/perfai/mcp-server.git
cd mcp-server
npm install
npm run build        # compile TS → dist/
npm start            # start MCP server
npm run dev          # watch mode
npm run mcp:inspect  # MCP Inspector UI at http://localhost:6274

🔍 Troubleshooting

| Problem | Fix | | --------------------------------------------- | ---------------------------------------------------------- | | MCP error -32000: Connection closed | Use the exact args above (--package=@perfai/mcp@latest perfai-mcp-server). A bare npx @perfai/mcp is ambiguous and fails to launch. | | Browser doesn't open on login | Manually visit the URL shown in the tool response | | No organizations found | Run manage_organizations {"action": "refresh"} | | App not found by name | Run list_apps {} first and use the exact sequence number | | Protected tool says "Authentication required" | Run login first | | Stale issues after a fix | Wait a moment and re-run show_*_issues |

Debug logs go to stderr:

npm start 2> debug.log

🌟 Key Features

• Auth0 OAuth2 — secure browser-based login, no plaintext credentials in config
• Org & App selection — by sequence number, name/label partial match, or ID
• Issue filters — severity, status (Open/Dismissed), sort field & direction, keyword search, pagination
• Summary dashboard — single-call overview of security, design, quality, attack surface, and bug bounty savings
• AI fix prompts — generate actionable fix instructions for any issue by number, ID, or description
• Fix tracking — compare AI-fixed issues against post-run results to confirm resolution

📄 License

MIT — see LICENSE