# 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-mcpb-v0.0.2.mcpb](https://scanner.dev/mcpb/scanner-mcpb-v0.0.2.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:

```bash
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:

```json
{
  "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

6. 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:

   ```bash
   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:

```python
#!/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-6-20260320",
        allowed_tools=[
            "mcp__scanner__get_scanner_context",
            "mcp__scanner__get_docs",
            "mcp__scanner__get_top_columns",
            "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')}",
                    # Omit to use the latest version
                    "x-scnr-mcp-api-version": "0.0.2"
                }
            }
        }
    )

    # 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:

```bash
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.