# Install the Spyderbat MCP Server ## What is MCP? The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) lets AI assistants interact with external tools and data. The Spyderbat MCP server exposes tools for searching, investigating, and managing your Spyderbat environment through natural language. ## Prerequisites Before configuring the Spyderbat MCP server, you'll need: * A Spyderbat account with API access * A valid API key ([How to create one](https://docs.spyderbat.com/tutorials/integrations/how-to-set-up-your-spyderbat-api-key-and-use-the-spyderbat-api)) * An MCP-compatible client (Claude Code, Cursor, Windsurf, or VS Code with Cline/Continue) {% hint style="warning" %} **API Key Security** The Spyderbat MCP server authenticates via API key in the `Authorization` header (OAuth is not currently supported). Keep these guidelines in mind: * **API keys inherit the permissions of the user who created them** — treat them like passwords * **Never commit keys to version control** — store config files outside your repo or add them to `.gitignore` * **For Claude Code**, use `-s user` to store the configuration in `~/.claude/` rather than the project directory * **Rotate keys regularly** via the Spyderbat console {% endhint %} ## Quick Start Pick your client below, or use one-click install: **Claude Code** (one command, no file editing): ```bash claude mcp add --transport http -s user spyderbat https://api.spyderbat.com/mcp/v1/mcp --header "Authorization: Bearer " ``` **Other clients** — see [Client Configuration](#client-configuration) for Cursor, Windsurf, VS Code, and MCP Inspector. After setup, restart your client and try: *"List my Spyderbat organizations"* ## One-Click Install Install directly in your editor: [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.png)](cursor://anysphere.cursor-deeplink/mcp/install?name=spyderbat\&config=eyJ1cmwiOiJodHRwczovL2FwaS5zcHlkZXJiYXQuY29tL21jcC92MS9tY3AiLCJ0cmFuc3BvcnQiOiJzdHJlYW1hYmxlLWh0dHAiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgJHtpbnB1dDpTUFlERVJCQVRfQVBJX0tFWX0ifX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-007ACC?style=flat\&logo=visualstudiocode\&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22spyderbat%22%2C%22config%22%3A%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.spyderbat.com%2Fmcp%2Fv1%2Fmcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20%24%7Binput%3ASPYDERBAT_API_KEY%7D%22%7D%7D%7D) [![Add to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-dark.svg)](lmstudio://add_mcp?name=spyderbat\&config=eyJ1cmwiOiJodHRwczovL2FwaS5zcHlkZXJiYXQuY29tL21jcC92MS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgJHtpbnB1dDpTUFlERVJCQVRfQVBJX0tFWX0ifX0%3D) > **Note:** You'll be prompted to enter your Spyderbat API key during installation. [Create an API key](https://docs.spyderbat.com/tutorials/integrations/how-to-set-up-your-spyderbat-api-key-and-use-the-spyderbat-api) if you don't have one. ## MCP Server Endpoints The Spyderbat MCP server is deployed at the following endpoints: * **US Region**: `https://api.spyderbat.com/mcp/v1/mcp` * **Mumbai Region**: `https://api.mum.prod.spyderbat.com/mcp/v1/mcp` All examples below use the US endpoint. Replace the URL if your organization is in the Mumbai region. ## Client Configuration {% tabs %} {% tab title="Claude Code" %} Run the following command to add the Spyderbat MCP server: ```bash claude mcp add --transport http -s project spyderbat https://api.spyderbat.com/mcp/v1/mcp --header "Authorization: Bearer " ``` Use `-s project` for project-scoped config, or `-s user` for global config stored in `~/.claude/`. After adding the server, restart Claude Code for the changes to take effect. **Verify the connection:** ``` > List my Spyderbat organizations ``` {% endtab %} {% tab title="Cursor" %} Add the following to your Cursor MCP settings (Settings > MCP): ```json { "mcpServers": { "spyderbat": { "url": "https://api.spyderbat.com/mcp/v1/mcp", "transport": "streamable-http", "headers": { "Authorization": "Bearer " } } } } ``` **`transport`** must be `"streamable-http"`. After saving, restart Cursor for the changes to take effect. {% endtab %} {% tab title="Windsurf" %} Add the following to `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "spyderbat": { "serverUrl": "https://api.spyderbat.com/mcp/v1/mcp", "transport": "streamable-http", "headers": { "Authorization": "Bearer " } } } } ``` > **Note:** Windsurf uses `serverUrl` instead of `url` — copy-pasting from Cursor/VS Code configs won't work. After saving, restart Windsurf for the changes to take effect. {% endtab %} {% tab title="VS Code / Cline" %} In VS Code, open Cline settings and add the MCP server configuration: ```json { "cline.mcpServers": { "spyderbat": { "url": "https://api.spyderbat.com/mcp/v1/mcp", "transport": "streamable-http", "headers": { "Authorization": "Bearer " } } } } ``` After saving, reload VS Code for the changes to take effect. {% endtab %} {% tab title="MCP Inspector" %} [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a graphical debugging tool for testing MCP server connections and exploring available tools. **Setup:** 1. **Transport Type**: Select **Streamable HTTP** 2. **URL**: Enter the [endpoint](#mcp-server-endpoints) for your region 3. **Connection Type**: Select **Via Proxy** 4. **Authentication**: Enable **Custom Headers** and add: * **Key**: `Authorization` * **Value**: `Bearer ` 5. Click **Connect**
MCP Inspector connected to Spyderbat MCP server

MCP Inspector connected to Spyderbat MCP server

Once connected, you can browse available tools, view their schemas, and test them from the interface. {% endtab %} {% endtabs %} ## Example Prompts The AI uses `onboard`, `prime`, and `search_docs` to learn available tools, schemas, and query syntax automatically. You can prompt conversationally and the AI translates your intent into API calls. For search schema and operator details, see the [Search Reference](https://docs.spyderbat.com/reference/search). Here's a realistic triage session: 1. **Orient** — *"Get up to speed on Spyderbat. What tools do you have?"* Calls `onboard` and `prime` to learn available tools and investigation workflows. 2. **Check access** — *"What organizations do I have access to?"* Calls `list_organizations`, returns org names and UIDs. 3. **Triage** — *"Find the highest-scoring Spydertraces from the last 24 hours."* Searches `model_spydertrace` for `score > 50`, sorted descending. Traces bundle related processes, connections, and red flags into scored units — your triage queue. 4. **Investigate** — *"Dig into the top trace. What processes ran, what connections were made, and what triggered it?"* Calls `get_trace_contents` to pull processes, connections, and red flags linked to that trace. Walks the process tree via `ppuid` to show parent-child relationships. 5. **Attribute** — *"Where did that external connection come from? What pod and namespace?"* Searches `model_connection` by IP, resolves `pod_uid` via `get_objects` to get pod name, namespace, and node. 6. **Resolve** — *"That's a health probe — suppress it for this cluster."* Calls `suppress_trace` with `preview=true` to generate a suppression policy, then applies it scoped to the cluster after you confirm. ### Example Conversation ``` User: Find high-severity red flags in the prod-k8s cluster from the last 24 hours AI: I'll search event_redflag with: severity = "high" and cluster_name = "prod-k8s" start_time = "-24h" Found 3 results: - root_shell (MITRE TA0004.T1548) in namespace "payments" — score 82 - ssh_inside_container_detection (MITRE TA0008.T1021) in namespace "backend" — score 67 - nonk8s_container_detection (MITRE TA0005.T1610) in namespace "monitoring" — score 31 User: The nonk8s_container_detection in monitoring — what's the process tree? AI: Process lineage via ppuid: systemd → containerd-shim → bash → curl 127.0.0.1:8080/healthz This is a Kafka health check probe hitting localhost, not a suspicious container. User: Suppress it for the monitoring namespace. AI: Previewing suppression policy scoped to namespace "monitoring"... [shows policy preview, warnings, and scope] Apply? (yes/no) ``` {% hint style="info" %} **Context Window Usage** Broad searches can return large result sets that consume context window tokens. To keep responses useful, narrow time ranges, use specific filters, and ask the AI to summarize rather than dump all results. {% endhint %} ## Troubleshooting ### 401 Unauthorized * Verify your API key is valid and not expired * Check that the Authorization header format is exactly: `Bearer ` ### Connection Timeout * Check that your network can reach `api.spyderbat.com` * Verify the endpoint URL matches your organization's region ### Tools Not Appearing * Restart your MCP client after configuration changes * For Claude Code: exit and restart the CLI * For Cursor: fully restart the application ### Empty Search Results If searches return no data, walk through this debugging flow: 1. **Verify org access** — ask: *"List my organizations"* and confirm the UID matches 2. **Widen time range** — ask: *"What is the current time?"* (uses `get_current_time`) and check that your search window includes recent data 3. **Check schema** — ask: *"List available search schemas for my org"* to confirm the schema exists 4. **Check permissions** — verify your API key has access to the target organization ### Getting Help If you encounter issues not covered here, check the [Spyderbat documentation](https://docs.spyderbat.com/readme) or contact support. ## Video Walkthrough Watch a demonstration of the Spyderbat MCP server in action: