Getting Started

Scanner's Model Context Protocol (MCP) server connects your security data to AI agents across multiple tools and platforms. Choose your tool based on how you want to work, then follow the setup instructions below.

Note that using the MCP tools requires an API key with the Read and Query permissions on any indexes you want to investigate (or the team-level IndexReadAny and IndexQueryAny permissions). You can create an API key in the Scanner UI at Settings > API Keys.

Choosing Your Tool

These four tools represent the most common starting points for using Scanner MCP. Choose based on your preferred workflow:

Claude Desktop (Interactive)

• When to use: You want a conversational AI interface for exploring security data

• Best for: Alert triage, ad-hoc investigations, quick questions, back-and-forth refinement

• Example: "What's happening with this alert? Should I escalate?" (natural conversation mode)

Claude Code (Interactive + CLI)

• When to use: You want to run investigations from your terminal or automate them in scripts

• Best for: Terminal-based workflows, batch processing alerts, integration with incident response automation

• Example: Running investigations as part of a scripted alert response pipeline

Cursor (IDE)

• When to use: You're developing detection rules or writing Scanner queries

• Best for: Detection engineering, query development, writing and validating detection rules

• Example: Building new detection rules and testing them against your data in real-time

Claude Agent SDK (Autonomous)

• When to use: You want to automate routine investigations and security operations

• Best for: Scheduled hunting, continuous monitoring, alert triage at scale, autonomous response workflows

• Example: An agent that runs hourly to investigate the highest-severity alert, gather threat intelligence, create tickets, and notify your team

---

Interactive Workflows

Claude Desktop

Claude Desktop allows you to interact with Scanner directly in your chat conversations.

Download and Install:

1. Download the Scanner MCP Bundle extension: scanner.dev/mcpb/scanner-mcpb.mcpb

2. Double-click the downloaded file to install it as a Claude Desktop extension

3. A configuration form will appear

Configure:

1. In Scanner's UI, go to Settings > API Keys

2. Copy your Scanner API Key (you'll need to create one if you don't have it)

3. Identify your Scanner MCP Server URL:

   • Look at your API URL (it looks like https://api.your-env-here.scanner.dev)

   • Replace api. with mcp. and add /v1/mcp at the end

   • Result: https://mcp.your-env-here.scanner.dev/v1/mcp

4. Paste both values into the configuration form

5. Optionally adjust Default Max Rows and Default Query Timeout (defaults are fine to start)

6. Enable the extension

Start Using:

Open Claude Desktop and start chatting. Explore your security data using natural language. See Using MCP for Security Operations for concrete examples and workflows.

Claude Code

Claude Code allows you to access Scanner MCP from the command line, enabling queries within your development environment.

Install:

From a directory where you plan to run Claude Code, configure the Scanner MCP server:

claude mcp add \
  --transport http \
  scanner \
  https://mcp.your-env-here.scanner.dev/v1/mcp \
  --header "Authorization: Bearer API_KEY_HERE"

Replace:

• your-env-here with your Scanner environment (from Settings > API Keys)

• API_KEY_HERE with your Scanner API Key

Start Using:

Run claude to start an interactive session with access to Scanner. Ask natural language questions about your security data. See Using MCP for Security Operations for concrete examples and workflows.

Cursor

Cursor is a code editor with built-in Claude integration and native MCP support.

Install:

1. Open Cursor

2. Click Cursor > Settings > Cursor Settings (in the title bar)

3. Click Tools & MCP

4. Click Add Custom MCP

5. Edit the JSON configuration to add the Scanner MCP server:

{
  "mcpServers": {
    "scanner": {
      "url": "https://mcp.your-env-here.scanner.dev/v1/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer API_KEY_HERE"
      }
    }
  }
}

Replace:

• your-env-here with your Scanner environment (from Settings > API Keys)

• API_KEY_HERE with your Scanner API Key

1. Save the configuration

Start Using:

In Cursor's Composer or chat, ask Claude to query and explore your security data. See Using MCP for Security Operations for concrete examples and workflows.

Autonomous Workflows

Claude Agent SDK

The Claude Agent SDK allows you to build autonomous agents that interact with Scanner programmatically, running investigations and security operations without user intervention.

Install:

1. Create a requirements.txt file:

   claude-agent-sdk
   python-dotenv
   rich

2. Install dependencies:

   pip install -r requirements.txt

3. Set up environment variables in a .env file:

   ANTHROPIC_API_KEY=your-anthropic-api-key
   SCANNER_MCP_URL=https://mcp.your-env-here.scanner.dev/v1/mcp
   SCANNER_MCP_API_KEY=your-scanner-api-key

Build an Agent:

Create a Python script (e.g., agent.py) to run an autonomous investigation:

#!/usr/bin/env python3
import asyncio
import os
from dotenv import load_dotenv
from rich import print as rprint
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    load_dotenv()

    # Configure agent with Scanner MCP
    options = ClaudeAgentOptions(
        model="claude-sonnet-4-5-20250929",
        allowed_tools=[
            "mcp__scanner__get_scanner_context",
            "mcp__scanner__execute_query",
            "mcp__scanner__fetch_query_results",
        ],
        mcp_servers={
            "scanner": {
                "type": "http",
                "url": os.environ.get("SCANNER_MCP_URL"),
                "headers": {
                    "Authorization": f"Bearer {os.environ.get('SCANNER_MCP_API_KEY')}"
                }
            }
        }
    )

    # Run an autonomous investigation
    prompt = """
        Query Scanner to find the highest severity detection alert from
        the last 1 hour. Then perform the following investigation:

        1. Explain the alert: What is the detection rule looking for?
           What threat does it represent?

        2. Search for related activity: Find other events from the same
           user, source IP, or account within the past 24 hours that
           might indicate a broader attack or compromise.

        3. Assess impact: Which users, systems, or data are affected?
           What is the scope of this incident?

        4. Cite evidence: Reference specific log events and timestamps
           that support your findings.

        5. Classify the alert as either:
           - True Positive: Actual malicious activity with evidence
           - False Positive: Benign activity triggering the rule

           Include your confidence level (high/medium/low) and
           reasoning for the classification.
    """

    async for message in query(prompt=prompt, options=options):
        rprint(message)

if __name__ == "__main__":
    asyncio.run(main())

Start Using:

Run your agent:

python agent.py

Deploy your agent to run continuously, on a schedule (via cron, Lambda, etc.), or triggered by events. The agent will automatically query Scanner, analyze results, and generate reports based on your instructions.

---

Continue to Using MCP for Security Operations to explore practical examples and workflows for both interactive and autonomous use cases.