Docs / Surface / ai/mcp-server

MCP Server

Surface exposes an MCP-compatible JSON-RPC endpoint so AI assistants can scan files and payloads for malware without writing HTTP client code.

There are two ways to connect:

Hosted MCP endpoint: a remote URL you point a url-based MCP client at. Best for inline payload scanning, profiles, account, and usage. No install.
Local MCP server (npx @tendrl/surface-mcp): a stdio server that runs on your machine. Adds file scanning (including a fully offline mode where files never leave your machine) and API key management. See Local server below.

Hosted endpoint

code


POST https://your-instance.com/surface/mcp

Requires an API key: Authorization: Bearer <API_KEY>. The endpoint is POST-only JSON-RPC.

Note

The hosted endpoint is being validated against url-based MCP clients. If a url client fails to connect, use the local npx @tendrl/surface-mcp server instead.

Hosted tools

Tool	Description
`scan_payload`	Scan raw text content: messages, JSON, code snippets, tool calls. Detects prompt injection, SQL/XSS injection, credential leaks, malicious code
`get_scan`	Retrieve results for a deferred scan by scan ID
`get_scan_history`	Browse past scans (paginated)
`get_scan_detail`	Full result for a historical scan
`list_profiles`	List available scan profiles and their configurations
`create_profile`	Create a new scan profile
`update_profile`	Update an existing scan profile
`delete_profile`	Delete a scan profile
`get_account`	Account details
`get_usage`	Check scan quota (used vs monthly limit)
`list_api_keys`	List Surface API keys
`get_plans`	List available billing plans and scan limits
`search_docs`	Search Surface documentation and return relevant snippets

The hosted endpoint does not scan files. To scan files via MCP, use the local npx @tendrl/surface-mcp server, which exposes a scan_file tool.

Client setup (hosted endpoint)

These configs point a url-based client at the hosted endpoint.

Cursor

In .cursor/mcp.json:

json


{
  "mcpServers": {
    "surface": {
      "url": "https://your-instance.com/surface/mcp",
      "headers": {
        "Authorization": "Bearer <SURFACE_API_KEY>"
      }
    }
  }
}

VS Code

In .vscode/mcp.json:

json


{
  "servers": {
    "surface": {
      "type": "http",
      "url": "https://your-instance.com/surface/mcp",
      "headers": { "Authorization": "Bearer <SURFACE_API_KEY>" }
    }
  }
}

Claude Desktop

In claude_desktop_config.json:

json


{
  "mcpServers": {
    "surface": {
      "url": "https://your-instance.com/surface/mcp",
      "headers": {
        "Authorization": "Bearer <SURFACE_API_KEY>"
      }
    }
  }
}

Local server (npx) {#local-server-npx}

The @tendrl/surface-mcp npm package runs a local stdio MCP server. Use it for file scanning and API key management, or when a url-based client can't reach the hosted endpoint. It exposes a larger toolset than the hosted endpoint:

All hosted scanning/account/profile tools, plus:
scan_file: scan a file by absolute path
scan_bundle: scan several payloads (e.g. main.py, boot.py, config.json) in one call and get an aggregate deploy_safe go/no-go, for gating a device deployment before you flash
create_api_key / delete_api_key: manage Surface API keys

It also serves the Surface skills as MCP resources (see AI Skills). The hosted endpoint serves documentation as resources but not skills.

Add it to your MCP client config:

json


{
  "mcpServers": {
    "surface": {
      "command": "npx",
      "args": ["-y", "@tendrl/surface-mcp"],
      "env": {
        "SURFACE_KEY": "${SURFACE_KEY}"
      }
    }
  }
}

By default, scan_file, scan_payload, and scan_bundle upload to the Surface API. To scan fully offline (content never leaves your machine), set SURFACE_SCANNER_PATH to a local scanner binary. All three then run every scan through the local binary instead:

json


{
  "mcpServers": {
    "surface": {
      "command": "npx",
      "args": ["-y", "@tendrl/surface-mcp"],
      "env": {
        "SURFACE_KEY": "${SURFACE_KEY}",
        "SURFACE_SCANNER_PATH": "/path/to/scanner"
      }
    }
  }
}

See Scanner Binary for details on local vs API mode.

← Back to Surface docs