MCP Server

The Surfinguard MCP (Model Context Protocol) Server exposes all 18 analyzers as tools that AI assistants can call directly. It runs locally using the CoreEngine with zero network dependencies.

What is MCP?

The Model Context Protocol is an open standard for connecting AI assistants to external tools and data sources. When you configure Surfinguard as an MCP server, AI assistants like Claude Desktop and Cursor can automatically check actions for security risks before executing them.

Setup

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "surfinguard": {
      "command": "npx",
      "args": ["@surfinguard/mcp-server"]
    }
  }
}

Cursor

Add to your Cursor MCP configuration (.cursor/mcp.json in your project):

{
  "mcpServers": {
    "surfinguard": {
      "command": "npx",
      "args": ["@surfinguard/mcp-server"]
    }
  }
}

VS Code (with MCP extension)

Add to your VS Code settings or MCP configuration:

{
  "mcpServers": {
    "surfinguard": {
      "command": "npx",
      "args": ["@surfinguard/mcp-server"]
    }
  }
}

Running Manually

You can also start the server directly:

npx @surfinguard/mcp-server

Or if installed globally:

surfinguard mcp-server

Available Tools

The MCP server exposes 19 tools (18 typed + 1 universal):

Universal Tool

Tool	Parameters	Description
`surfinguard_check`	`type`, `value`, `metadata?`	Check any action type

Typed Tools

Tool	Parameters	Description
`surfinguard_check_url`	`url`	Check a URL for phishing/scam indicators
`surfinguard_check_command`	`command`	Check a shell command for dangerous operations
`surfinguard_check_text`	`text`	Check text for prompt injection
`surfinguard_check_file_read`	`path`	Check if reading a file path is safe
`surfinguard_check_file_write`	`path`, `content?`	Check if writing to a file path is safe
`surfinguard_check_api_call`	`value`, `metadata?`	Check an API call for SSRF, credential forwarding
`surfinguard_check_query`	`query`	Check a database query for injection/exfiltration
`surfinguard_check_code`	`code`, `metadata?`	Check code for malicious patterns
`surfinguard_check_message`	`message`, `metadata?`	Check a message for social engineering
`surfinguard_check_transaction`	`value`, `metadata?`	Check a financial transaction
`surfinguard_check_auth`	`value`, `metadata?`	Check an authentication action
`surfinguard_check_git`	`value`, `metadata?`	Check a Git operation
`surfinguard_check_ui_action`	`value`, `metadata?`	Check a UI interaction
`surfinguard_check_infra`	`value`, `metadata?`	Check an infrastructure operation
`surfinguard_check_agent_comm`	`value`, `metadata?`	Check agent communication
`surfinguard_check_data_pipeline`	`value`, `metadata?`	Check a data pipeline operation
`surfinguard_check_document`	`value`, `metadata?`	Check a document operation
`surfinguard_check_iot`	`value`, `metadata?`	Check an IoT device command

Tool Response Format

Each tool returns a structured response:

{
  "score": 9,
  "level": "DANGER",
  "primitives": {
    "DESTRUCTION": 0,
    "EXFILTRATION": 4,
    "ESCALATION": 0,
    "PERSISTENCE": 0,
    "MANIPULATION": 9
  },
  "reasons": [
    "Brand impersonation: google",
    "Risky TLD: .tk",
    "Suspicious path: /verify"
  ],
  "threats": [
    { "id": "U05", "name": "Brand impersonation", "score": 5, "primitive": "MANIPULATION" },
    { "id": "U04", "name": "Risky TLD", "score": 3, "primitive": "MANIPULATION" }
  ]
}

How It Works

The MCP server uses the stdio transport protocol. When an AI assistant starts a session:

The server initializes the CoreEngine with all 18 analyzers
Tools are registered and advertised to the AI assistant
When the assistant calls a tool, the CoreEngine analyzes the action locally
The result is returned to the assistant, which can use it to make decisions

All analysis happens locally — no data is sent to any external server. This makes the MCP server suitable for sensitive environments where data cannot leave the machine.

Example Usage in Claude

Once configured, Claude will automatically have access to the Surfinguard tools. You can ask it to check actions:

“Check if this URL is safe: https://paypa1-verify.tk/login”

Claude will call surfinguard_check_url and report the findings:

The URL has been flagged as DANGER (score: 9). Detected threats:

Brand impersonation of PayPal (U05)

Risky TLD .tk (U04)

Suspicious path /login (U07)

This URL should not be visited.

CLI Authentication