> ## Documentation Index > Fetch the complete documentation index at: https://docs.infrawatch.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP server > Supercharge your SOC by giving your own AI agents the Infrawatch dataset Your agents already write the queries. Now they can run them. The Infrawatch MCP server puts the internet's attack surface inside Claude, ChatGPT, Cursor, or anything else that speaks the Model Context Protocol. Ask your agent to triage an alert, scope a red team engagement, or check whether an IP has ever hosted an infostealer, and it searches 400 million services, passive DNS, fingerprints, proxy intelligence, and reporting on your behalf, then shows its working. No wrapper, no proxy, no SDK. One URL and your existing API key. ## What your agent can do Every tool is read-only. Your agent can search and read, and it cannot create, change, or delete anything in your account. Because every detection carries a [taxonomy](/platform/taxonomy) category, your agent can ask precise questions instead of keyword-matching. Categories are hierarchical, so `malware/*` covers every malware family path while `malware/infostealer` stays narrow. | Ask your agent | What it searches | | ------------------------------------------------------ | --------------------------------------------- | | "Has an infostealer ever been hosted on 203.0.113.10?" | `tags.category:"malware/infostealer"` | | "Was a proxy running on this host?" | `services.tags.category:proxy/*` | | "Is this a known C2?" | `tags.category:"malware/c2"` | | "Find credential harvesting pages on our domains" | `tags.category:"phishing/credential-harvest"` | | "Show exposed admin panels in our ASN" | `tags.category:"exposure/admin-panel"` | | "Anything malicious in this range?" | `tags.category:"malware/*"` | Your agent writes the InfraQL. You can ask in plain language and read the query it ran. ## Before you start You need an Infrawatch API key. Create one in [API access](https://app.infrawatch.com/accounts/api-access) and give it the scopes the work needs: `search.view` for search, `reports.view` for reporting, and the relevant `esi.*.view` scopes for project data. Your API key is a credential. Keep it in your client's secret storage or an environment variable, and never commit it to a repository. The endpoint is: ```text theme={null} https://api.infrawatch.com/mcp/v1 ``` Authenticate with the same `X-API-Key` header the REST API uses. That is the only accepted form. Bearer tokens are not accepted. ## Claude ```bash theme={null} claude mcp add --transport http infrawatch https://api.infrawatch.com/mcp/v1 \ --header "X-API-Key: " ``` To share the setup with your team, commit a `.mcp.json` that reads the key from the environment instead of embedding it: ```json theme={null} { "mcpServers": { "infrawatch": { "type": "http", "url": "https://api.infrawatch.com/mcp/v1", "headers": { "X-API-Key": "${INFRAWATCH_API_KEY}" } } } } ``` Open **Settings → Connectors → Add custom connector**, then enter the endpoint URL and add `X-API-Key` with your key as a request header. ## ChatGPT and Codex Add the server to `~/.codex/config.toml`. `env_http_headers` points at the environment variable holding your key, so the key itself stays out of the file: ```toml theme={null} [mcp_servers.infrawatch] url = "https://api.infrawatch.com/mcp/v1" env_http_headers = { "X-API-Key" = "INFRAWATCH_API_KEY" } ``` Do not use `bearer_token_env_var`. It sends `Authorization: Bearer`, which this endpoint does not accept. In **Settings → Connectors**, create a custom connector pointing at the endpoint URL and set `X-API-Key` as a request header. ## Cursor Add Infrawatch MCP server to Cursor Click the button, confirm the server in Cursor, then replace `` in the generated entry with your key. Or add it to `~/.cursor/mcp.json` by hand: ```json theme={null} { "mcpServers": { "infrawatch": { "url": "https://api.infrawatch.com/mcp/v1", "headers": { "X-API-Key": "" } } } } ``` ## Try it Once connected, ask in plain language. ### Triage an alert ```text Verdict on an IP theme={null} Our EDR flagged 203.0.113.10. Has it ever hosted an infostealer or C2? Show me the services observed and when. ``` ```text Was it a proxy theme={null} Was a residential proxy running on 203.0.113.10 at any point? If so, on which ports? ``` ```text Reporting theme={null} Has this indicator appeared in any threat report? Summarise what was said about it. ``` ### Red teaming Scope an engagement from the outside, exactly as an attacker would see it. Nothing here touches the target: it is all prior observation. ```text Scope the perimeter theme={null} Map the external footprint of example.com. Find subdomains, then flag anything with an exposed admin panel or remote access service. ``` ```text Find the forgotten theme={null} Show dangling DNS on our domains, and any directory listings left open. Sort by what looks most recently changed. ``` ```text Pick the way in theme={null} Across our ASN, which hosts expose a remote access service? Group them by product so I can see what is worth a closer look. ``` Red team work stays within your authorisation. Infrawatch reports what it has already observed from the public internet, so scoping an engagement never sends traffic to the target. ### Hunt ```text Malware infrastructure theme={null} Find hosts in this /24 tagged as malware infrastructure in the last 90 days, then count them by ASN. ``` ```text Phishing kits theme={null} Any credential harvesting pages using our brand name in the certificate? ``` ```text Watch your own surface theme={null} List my projects, then show assets in the production project that gained a new open port this week. ``` Project-scoped questions need a project UUID. Ask your agent to list your projects first. It has a tool for that and will chain the two calls itself. ## Billing MCP is billed as ordinary API usage. There is no separate MCP plan, no per-seat charge, and no premium rate. | Action | Cost | | -------------------------------------- | ------------- | | Connecting a client | Free | | Your agent listing the available tools | Free | | Your agent calling a tool | 1 API request | A tool call is an API request, metered exactly as if you had called the endpoint yourself with `curl`. It counts against the same monthly quota, obeys the same rate limits, and is subject to the same scopes on the same key. That makes usage easy to predict: **one question that takes your agent five searches costs five API requests.** To watch it live, ask your agent for your current usage. It reports your quota and remaining balance, and that check is itself free. Because everything runs on your key's existing scopes, an agent can never reach data you could not reach yourself. Narrow the key's scopes to narrow what your agent can see. ## When something goes wrong Your agent sees the API's own error, so it can usually explain and correct itself. | What you see | Meaning | | ----------------------------- | ---------------------------------------------------- | | `unauthorized` | The key is missing, invalid, expired, or revoked | | `permission_denied` | The key is valid but lacks the scope that tool needs | | `account_api_quota_exceeded` | The monthly quota is spent | | `api_key_rate_limit_exceeded` | Too many requests too quickly; retry shortly | If no tools appear at all, check that the URL is exactly `https://api.infrawatch.com/mcp/v1` and that your header name is `X-API-Key`. Scopes, headers, and error handling for the underlying API. Read and adapt the queries your agent runs.