PerfAI MCP Server

A specialized Model Context Protocol (MCP) server for PerfAI Security Analysis with Auth0 authentication.

📦 Installation (from npm)

Install globally (CLI):

npm install -g @perfai/mcp-server

Or add as a project dependency:

npm install @perfai/mcp-server --save-dev

🚀 Run (CLI)

perfai-mcp-server

This starts the MCP server over stdio. Use with an MCP client (Cursor, VS Code, MCP Inspector).

Optional Environment Variables

You can override Auth0 settings:

set PERFAI_AUTH0_DOMAIN=auth.perfai.ai
set PERFAI_AUTH0_CLIENT_ID=yourClientId

PKCE flow is enabled; no client secret is required or bundled.

🧩 Programmatic Usage

import { startServer, authManager, AuthenticationManager } from '@perfai/mcp-server';

// Start server (returns a promise)
await startServer();

All logging is written to stderr to remain MCP-compatible.

🔐 Authentication & Security

🎯 Universal Device Code Authentication - Works with ANY MCP client without configuration!

• 🔑 Auth0 Integration: Seamless integration with auth.perfai.ai
• 🌐 Zero Configuration: No redirect URLs needed - works everywhere
• 📱 Device Code Flow: Simple browser authentication like Netflix/GitHub
• 🛡️ Session Management: Secure token storage and automatic validation
• 🔄 Auto-Detection: Server automatically detects authentication completion
• 👥 Multi-User Support: Isolated sessions for different users

🛠️ Available Tools

🔓 Public Tools (No authentication required)

• 🔐 login: Authenticate with PerfAI using OAuth2 Device Code flow
• 📊 auth_status: Check current authentication status and user information

🔒 Protected Tools (Authentication required)

👤 User Management

• 👤 user_info: Get detailed authenticated user information
• 🚪 logout: Clear authentication session and logout

🏢 Organization Management

• 🏢 manage_organizations: List, select, and refresh organizations
  • Actions: list, select, refresh
• 📋 list_apis: List all APIs available in current organization
• 🎯 select_api: Select an API for use with other tools

🔒 Security Analysis

• 🔒 show_security_issues: List security vulnerabilities by organization
  • Supports pagination, search, and severity filtering
• 🤖 ai_fix_security_issue: Generate AI-powered remediation prompts
  • Works with issue IDs or descriptive text
• 📋 show_fixed_issues: View all AI-fixed security issues in current session

🚀 Security Testing

• 🚀 run_security_test: Execute comprehensive security analysis using Docker
  • Requires OpenAPI spec URL and local API base path
  • Uses PerfAI's Docker-based security testing engine

🚀 Quick Start (Local Development)

1. Install Dependencies

npm install

2. Build the Project

npm run build

3. Start the Server (built output)

npm start

Or directly via ts-node (optional):

npx ts-node src/index.ts

4. Test with MCP Inspector (Optional)

npm run mcp:inspect

🔧 MCP Client Configuration

For Cursor

Add to your cursor_mcp_config.json:

{
  "mcpServers": {
    "perfai-mcp": {
      "command": "node",
      "args": ["C:\\path\\to\\MCP_prefai\\dist\\index.js"],
      "env": {}
    }
  }
}

For VS Code

Add to your vscode_mcp_config.json:

{
  "mcpServers": {
    "perfai-mcp": {
      "command": "node",
      "args": ["C:\\path\\to\\MCP_prefai\\dist\\index.js"],
      "env": {}
    }
  }
}

🧪 Authentication Flow

Step-by-Step Authentication

1. Check Initial Status: Run auth_status → Shows "Not Authenticated"
2. Login: Run login tool:
   • ✅ Browser automatically opens to PerfAI Auth0 device page
   • 📱 You'll see a simple code (e.g., BDJK-WHNZ)
   • 🔐 Enter the code in browser and complete authentication
   • 🔄 Server automatically detects completion
3. Verify: Run auth_status → Shows user info and "Authenticated"
4. Use Protected Tools: All 9 protected tools now available
5. Logout: Run logout → Returns to 2 public tools only

Security Features

• 🔒 Zero Configuration: No Auth0 redirect URL setup required
• 🌐 Universal Compatibility: Works with any MCP client
• ⏰ Auto-Expiry: Tokens automatically expire for security
• 🔄 Session Isolation: Each user session is completely isolated

📋 Tool Usage Examples

Organization Management

# List available organizations
manage_organizations {"action": "list"}

# Select an organization
manage_organizations {"action": "select", "org_id": "your-org-id"}

# Refresh organization list
manage_organizations {"action": "refresh"}

Security Analysis

# List security issues
show_security_issues {"limit": 20}

# Search for specific app issues
show_security_issues {"search": "myapp", "limit": 10}

# Generate AI fix for an issue
ai_fix_security_issue {"issue_id": "issue-id-here"}

# Show all fixed issues
show_fixed_issues {}

API Management

# List available APIs
list_apis {}

# Select an API for testing
select_api {"api_id": "your-api-id"}

Security Testing

# Run comprehensive security test
run_security_test {
  "spec_url": "http://localhost:3000/swagger.json",
  "local_base_path": "http://localhost:3000"
}

🏗️ Development

Watch Mode

npm run dev

Available Scripts

• npm run build – Compile TypeScript to JavaScript
• npm run dev – Watch mode for development
• npm start – Start the MCP server
• npm run mcp:inspect – Start MCP Inspector for testing

Project Structure

├── src/
│   └── index.ts              # Main MCP server implementation
├── dist/                     # Compiled JavaScript output
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── cursor_mcp_config.json    # Cursor MCP client config
├── vscode_mcp_config.json    # VS Code MCP client config
└── README.md                 # This file

🔍 Troubleshooting

Publishing (Maintainers)

# Bump version (choose patch|minor|major)
npm version patch

# Publish (scoped public)
npm publish --access public

If you see 403 errors ensure: (1) You're logged in (npm whoami), (2) The @perfai scope exists and you have publish rights, (3) Version not already published.

Common Issues

Authentication Problems

• Browser doesn't open: Manually visit the URL shown in the login response
• Code expired: Run login again to get a new device code
• Stuck on authentication: Check browser for any error messages

Organization Issues

• No organizations found: Run manage_organizations {"action": "refresh"}
• Permission denied: Ensure your PerfAI account has organization access

API Testing Issues

• Docker errors: Ensure Docker Desktop is running
• Invalid URLs: Verify your API is accessible and spec URL is valid
• Timeout: Large APIs may take longer; check Docker logs

Debug Mode

The server logs all activity to stderr, making debugging easier:

npm start 2> debug.log  # Capture debug logs

🌟 Features

• 🎯 PerfAI-Focused: Built specifically for PerfAI security workflows
• 🔐 Secure Authentication: OAuth2 Device Code flow with session management
• 📊 Comprehensive Analysis: Full security issue management and AI-powered fixes
• 🐳 Docker Integration: Containerized security testing engine
• 🔄 Real-time Updates: Live tool list updates based on authentication state
• 📱 Universal Client Support: Works with Cursor, VS Code, and any MCP client

🚀 Ready to secure your APIs with PerfAI's MCP integration!