@rad-security/mcp-server 0.0.36-5.g3825a61 → 0.0.36

package/README.md

@@ -8,212 +8,225 @@ A Model Context Protocol (MCP) server for RAD Security, providing AI-powered sec
   <img width="380" height="200" src="https://glama.ai/mcp/servers/@rad-security/mcp-server/badge" alt="RAD Security MCP server" />
 </a>
 
-## Connect (hosted — recommended)
+## Installation
 
-RAD Security runs the MCP server for you, so most users don't need to install or host anything. Point your MCP client at the hosted endpoint and authenticate with your RAD Security credentials.
+```bash
+npm install @rad-security/mcp-server
+```
 
-- **Endpoint:** `https://api.rad.security/mcp/` — note the **trailing slash**.
-- **Transport:** Streamable HTTP.
-- **Authentication:** send your credential in the `Authorization` header:
+## Usage
 
-  ```
-  Authorization: Bearer <access_key_id>:<secret_key>:<account_id>
-  ```
+### Prerequisites
 
-  `<access_key_id>` and `<secret_key>` are a RAD Security API access key (create one in the RAD Security console); `<account_id>` is your account ID. The server authenticates every request against the RAD Security API — no credentials are stored server-side.
+- Node.js 20.x or higher
 
-> A short-lived form `Bearer ory_st_<session_token>:<account_id>` also works, but session tokens expire — prefer an access key for anything long-lived (e.g. Slack / Claude Tag).
+### Environment Variables
 
-### Claude Code
+The following environment variables are required to use the MCP server with Rad Security:
 
 ```bash
-claude mcp add --transport http rad-security https://api.rad.security/mcp/ \
-  --header "Authorization: Bearer <access_key_id>:<secret_key>:<account_id>"
+RAD_SECURITY_ACCESS_KEY_ID="your_access_key"
+RAD_SECURITY_SECRET_KEY="your_secret_key"
+RAD_SECURITY_ACCOUNT_ID="your_account_id"
 ```
 
-### OpenAI Codex CLI
-
-`~/.codex/config.toml`:
+Optional environment variables:
 
-```toml
-[mcp_servers.rad-security]
-url = "https://api.rad.security/mcp/"
-http_headers = { "Authorization" = "Bearer <access_key_id>:<secret_key>:<account_id>" }
+```bash
+RAD_SECURITY_TENANT_ID="your_tenant_id"  # Optional: If not provided, will be fetched automatically from the account
 ```
 
-Or via the CLI, keeping the secret in an env var (`export RAD_MCP_TOKEN=<access_key_id>:<secret_key>:<account_id>`):
+#### Optional: Filter Toolkits
 
-```bash
-codex mcp add rad-security --url https://api.rad.security/mcp/ --bearer-token-env-var RAD_MCP_TOKEN
-```
+You can control which toolkits are exposed by the MCP server using these environment variables:
 
-### Cursor
+- `INCLUDE_TOOLKITS`: Comma-separated list of toolkits to include (only these will be enabled)
+- `EXCLUDE_TOOLKITS`: Comma-separated list of toolkits to exclude (all except these will be enabled)
 
-`.cursor/mcp.json`:
+Available toolkits:
+- `containers` - Container inventory operations
+- `clusters` - Kubernetes cluster operations
+- `audit` - Audit log operations
+- `images` - Container image, vulnerability and CVE disposition operations
+- `kubeobject` - Kubernetes resource operations
+- `runtime` - Runtime analysis operations
+- `findings` - Security findings operations
+- `inbox` - Inbox item operations
+- `workflows` - Workflow execution operations
+- `custom_workflows` - Workflow authoring operations (disabled by default)
+- `knowledge_base` - Knowledge base search operations
+- `radql` - Query interface for rad data platform
+- `dashboards` - Dashboard and widget template operations
+- `integrations` - External integration operations
 
-```json
-{
-  "mcpServers": {
-    "rad-security": {
-      "type": "http",
-      "url": "https://api.rad.security/mcp/",
-      "headers": {
-        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
-      }
-    }
-  }
-}
+Note: `custom_workflows` is disabled by default and must be enabled explicitly via `INCLUDE_TOOLKITS`.
+
+#### Inbound authentication (`MCP_AUTH_MODE`)
+
+When running over the streamable HTTP transport, the server can authenticate each
+inbound request instead of using a single set of process-env credentials. This is
+what makes a single deployment safe to serve multiple accounts (for example, when
+hosting the server as a remote connector).
+
+- `MCP_AUTH_MODE=env` (default) — every session uses the `RAD_SECURITY_*`
+  environment credentials. Single-tenant; unauthenticated at the HTTP layer.
+  This preserves the existing local / self-hosted / per-account-pod behavior.
+- `MCP_AUTH_MODE=header` — every session must present its own credential in the
+  `Authorization` header. A missing or malformed header is rejected with
+  `401 Unauthorized`. Only supported with `TRANSPORT_TYPE=streamable`
+  (the server refuses to start otherwise).
+
+In `header` mode the bearer credential encodes the account, in one of two forms:
+
+```
+Authorization: Bearer <access_key_id>:<secret_key>:<account_id>
+Authorization: Bearer ory_st_<session_token>:<account_id>
 ```
 
-### VS Code (GitHub Copilot)
+`RAD_SECURITY_API_URL` is still taken from server configuration (not the caller).
+The credential shape is validated on connect; whether it actually authenticates
+against the Rad API surfaces on the first tool call.
 
-`.vscode/mcp.json` — note the wrapper key is `servers`, not `mcpServers`:
+> **Note:** exposing the server publicly requires `MCP_AUTH_MODE=header` (or an
+> authenticating proxy in front). The default `env` mode does **not** authenticate
+> inbound HTTP requests and must not be reachable from untrusted networks.
 
-```json
-{
-  "servers": {
-    "rad-security": {
-      "type": "http",
-      "url": "https://api.rad.security/mcp/",
-      "headers": {
-        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
-      }
-    }
-  }
-}
+Examples:
+
+```bash
+# Only enable workflow toolkit
+INCLUDE_TOOLKITS="workflows"
+
+# Enable only containers and images toolkits
+INCLUDE_TOOLKITS="containers,images"
+
+# Exclude workflow toolkit (enable all others)
+EXCLUDE_TOOLKITS="workflows"
+
+# Exclude runtime toolkit
+EXCLUDE_TOOLKITS="runtime"
 ```
 
-### Gemini CLI
+Note: If `INCLUDE_TOOLKITS` is set, `EXCLUDE_TOOLKITS` is ignored.
 
-`~/.gemini/settings.json` — note the URL field is `httpUrl` (not `url`):
+### In cursor IDE
 
-```json
-{
-  "mcpServers": {
-    "rad-security": {
-      "httpUrl": "https://api.rad.security/mcp/",
-      "headers": {
-        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
-      }
-    }
-  }
-}
+It's quite problematic to set ENV variables in cursor IDE.
+
+So, you can use the following start.sh script to start the server.
+
+```bash
+./start.sh
 ```
 
-### Cline
+Please set the ENV variables in the start.sh script first!
+
+### In Claude Desktop
 
-`cline_mcp_settings.json` — note `type` must be exactly `streamableHttp` (camelCase):
+You can use the following config to start the server in Claude Desktop.
 
 ```json
 {
   "mcpServers": {
     "rad-security": {
-      "type": "streamableHttp",
-      "url": "https://api.rad.security/mcp/",
-      "headers": {
-        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
+      "command": "npx",
+      "args": ["-y", "@rad-security/mcp-server"],
+      "env": {
+        "RAD_SECURITY_ACCESS_KEY_ID": "<your-access-key-id>",
+        "RAD_SECURITY_SECRET_KEY": "<your-secret-key>",
+        "RAD_SECURITY_ACCOUNT_ID": "<your-account-id>"
       }
     }
   }
 }
 ```
 
-### Windsurf
-
-`~/.codeium/windsurf/mcp_config.json` — note the URL field is `serverUrl`:
+To filter toolkits, add `INCLUDE_TOOLKITS` or `EXCLUDE_TOOLKITS` to the env:
 
 ```json
 {
   "mcpServers": {
     "rad-security": {
-      "serverUrl": "https://api.rad.security/mcp/",
-      "headers": {
-        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
+      "command": "npx",
+      "args": ["-y", "@rad-security/mcp-server"],
+      "env": {
+        "RAD_SECURITY_ACCESS_KEY_ID": "<your-access-key-id>",
+        "RAD_SECURITY_SECRET_KEY": "<your-secret-key>",
+        "RAD_SECURITY_ACCOUNT_ID": "<your-account-id>",
+        "EXCLUDE_TOOLKITS": "workflows"
       }
     }
   }
-}
 ```
 
-### Other clients
-
-Most MCP clients accept a remote Streamable HTTP server with a URL and an `Authorization` header — only the field names differ. Keep the **trailing slash** on the URL in every case.
+### As a Docker Container - with Streamable HTTP
 
-| Client | Config location | URL field | Transport marker | Header field |
-| --- | --- | --- | --- | --- |
-| Claude Code | `claude mcp add` | positional arg | `--transport http` | `--header` |
-| OpenAI Codex CLI | `~/.codex/config.toml` | `url` | inferred | `http_headers` / `bearer_token_env_var` |
-| Cursor | `.cursor/mcp.json` | `url` | `type: "http"` | `headers` |
-| VS Code | `.vscode/mcp.json` (`servers`) | `url` | `type: "http"` | `headers` |
-| Gemini CLI | `~/.gemini/settings.json` | `httpUrl` | inferred | `headers` |
-| Cline | `cline_mcp_settings.json` | `url` | `type: "streamableHttp"` | `headers` |
-| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `serverUrl` | inferred | `headers` |
+```bash
+docker build -t rad-security/mcp-server .
+docker run \
+  -e TRANSPORT_TYPE=streamable \
+  -e RAD_SECURITY_ACCESS_KEY_ID=your_access_key \
+  -e RAD_SECURITY_SECRET_KEY=your_secret_key \
+  -e RAD_SECURITY_ACCOUNT_ID=your_account_id \
+  -p 3000:3000 \
+  rad-security/mcp-server
+```
 
-### Claude.ai / Claude Desktop / Claude Tag (Slack)
+With toolkit filters:
 
-These surfaces add remote MCP servers as **connectors**, which use their own credential settings rather than a raw request header. Add `https://api.rad.security/mcp/` as a custom connector, then supply the bearer credential through the connector's settings:
+```bash
+docker run \
+  -e TRANSPORT_TYPE=streamable \
+  -e RAD_SECURITY_ACCESS_KEY_ID=your_access_key \
+  -e RAD_SECURITY_SECRET_KEY=your_secret_key \
+  -e RAD_SECURITY_ACCOUNT_ID=your_account_id \
+  -e INCLUDE_TOOLKITS=workflows,containers \
+  -p 3000:3000 \
+  rad-security/mcp-server
+```
 
-- **Claude Tag (Slack):** attach the server as a plugin whose `.mcp.json` points at the endpoint, and add the bearer credential on the Access bundle's **Credentials** tab. See [Claude Tag — connect a custom MCP server](https://claude.com/docs/claude-tag/admins/connections/custom).
-- **Claude.ai / Desktop:** add it under Settings → Connectors; see [custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
+### As a Docker Container - multi-tenant (per-request auth)
 
-### Test it (MCP Inspector or curl)
+Serve multiple accounts from one deployment by requiring each request to carry its
+own credential. Note there are no `RAD_SECURITY_ACCESS_KEY_ID` / `_SECRET_KEY` /
+`_ACCOUNT_ID` env vars here — those arrive per request in the `Authorization` header.
 
 ```bash
-npx @modelcontextprotocol/inspector
-# Transport:      Streamable HTTP
-# URL:            https://api.rad.security/mcp/   (trailing slash)
-# Custom headers: { "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>" }
+docker run \
+  -e TRANSPORT_TYPE=streamable \
+  -e MCP_AUTH_MODE=header \
+  -e RAD_SECURITY_API_URL=https://api.rad.security \
+  -p 3000:3000 \
+  rad-security/mcp-server
 ```
 
+Callers then authenticate per request:
+
 ```bash
 curl -H "authorization: Bearer <access_key_id>:<secret_key>:<account_id>" \
   -H "content-type: application/json" \
   -H "accept: application/json, text/event-stream" \
-  -X POST https://api.rad.security/mcp/ \
-  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
+  -X POST http://localhost:3000/mcp -d '{...}'
 ```
 
-### Scoping the tools an agent sees
-
-By default a connection gets every toolkit. To give an agent a smaller set — less context/token overhead, and least privilege — add a scoping header to that connection alongside `Authorization`. The subset is enforced: an out-of-scope tool is hidden from `tools/list` **and** rejected if called.
+### As a Docker Container - with SSE (deprecated)
 
-| Header | Effect |
-| --- | --- |
-| `X-Rad-Toolkits: findings, images` | only these toolkits |
-| `X-Rad-Exclude-Toolkits: workflows` | every toolkit except these |
-| `X-Rad-Readonly: true` | only read-only tools (drops the write tools) |
-
-Toolkits: `containers`, `clusters`, `audit`, `images`, `kubeobject`, `runtime`, `findings`, `inbox`, `workflows`, `knowledge_base`, `radql`, `dashboards`, `integrations` (plus `custom_workflows`, off by default).
-
-Example — a read-only findings/images agent (any client that supports headers; Cursor shown):
-
-```json
-{
-  "mcpServers": {
-    "rad-security-findings": {
-      "type": "http",
-      "url": "https://api.rad.security/mcp/",
-      "headers": {
-        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>",
-        "X-Rad-Toolkits": "findings, images",
-        "X-Rad-Readonly": "true"
-      }
-    }
-  }
-}
-```
-
-In Claude Code, pass an extra `--header`:
+*Note:* The SSE transport is now deprecated in favor of Streamable HTTP. It's still supported for backward compatibility, but it's recommended to use Streamable HTTP instead.
 
 ```bash
-claude mcp add --transport http rad-security https://api.rad.security/mcp/ \
-  --header "Authorization: Bearer <access_key_id>:<secret_key>:<account_id>" \
-  --header "X-Rad-Toolkits: findings, images"
+docker build -t rad-security/mcp-server .
+docker run \
+  -e TRANSPORT_TYPE=sse \
+  -e RAD_SECURITY_ACCESS_KEY_ID=your_access_key \
+  -e RAD_SECURITY_SECRET_KEY=your_secret_key \
+  -e RAD_SECURITY_ACCOUNT_ID=your_account_id \
+  -p 3000:3000 \
+  rad-security/mcp-server
 ```
 
 ## Features
 
-All tools require authentication and an account in RAD Security. The hosted endpoint exposes every toolkit below except `custom_workflows` (workflow authoring), which is off by default.
+All tools require authentication and an account in Rad Security.
 
 - Account Inventory
   - List clusters and their details
@@ -273,93 +286,6 @@ All tools require authentication and an account in RAD Security. The hosted endp
   - Build queries programmatically from structured conditions
   - Execute multiple queries in parallel
 
-## Self-hosting
-
-Prefer to run the server yourself — for example an air-gapped environment, data-residency requirements, or if you don't want to route through the hosted gateway? It's published to npm and as a container image.
-
-### Prerequisites
-
-- Node.js 20.x or higher
-
-### Credentials
-
-Provide your RAD Security credentials via environment variables:
-
-```bash
-RAD_SECURITY_ACCESS_KEY_ID="your_access_key"
-RAD_SECURITY_SECRET_KEY="your_secret_key"
-RAD_SECURITY_ACCOUNT_ID="your_account_id"
-
-# Optional: fetched automatically from the account if not set
-RAD_SECURITY_TENANT_ID="your_tenant_id"
-```
-
-### npx (stdio) — e.g. Claude Desktop
-
-```json
-{
-  "mcpServers": {
-    "rad-security": {
-      "command": "npx",
-      "args": ["-y", "@rad-security/mcp-server"],
-      "env": {
-        "RAD_SECURITY_ACCESS_KEY_ID": "<your-access-key-id>",
-        "RAD_SECURITY_SECRET_KEY": "<your-secret-key>",
-        "RAD_SECURITY_ACCOUNT_ID": "<your-account-id>"
-      }
-    }
-  }
-}
-```
-
-### Docker (Streamable HTTP)
-
-```bash
-docker build -t rad-security/mcp-server .
-docker run \
-  -e TRANSPORT_TYPE=streamable \
-  -e RAD_SECURITY_ACCESS_KEY_ID=your_access_key \
-  -e RAD_SECURITY_SECRET_KEY=your_secret_key \
-  -e RAD_SECURITY_ACCOUNT_ID=your_account_id \
-  -p 3000:3000 \
-  rad-security/mcp-server
-```
-
-### Toolkit filtering
-
-Control which toolkits a self-hosted server exposes:
-
-- `INCLUDE_TOOLKITS`: comma-separated list of toolkits to include (only these are enabled).
-- `EXCLUDE_TOOLKITS`: comma-separated list of toolkits to exclude (all others are enabled). Ignored if `INCLUDE_TOOLKITS` is set.
-
-Available toolkits: `containers`, `clusters`, `audit`, `images`, `kubeobject`, `runtime`, `findings`, `inbox`, `workflows`, `custom_workflows` (disabled by default), `knowledge_base`, `radql`, `dashboards`, `integrations`.
-
-```bash
-# Only the workflows toolkit
-INCLUDE_TOOLKITS="workflows"
-
-# Everything except runtime
-EXCLUDE_TOOLKITS="runtime"
-```
-
-### Multi-tenant (per-request auth)
-
-`MCP_AUTH_MODE` controls how a streamable HTTP deployment authenticates inbound requests — this is what the hosted endpoint uses:
-
-- `MCP_AUTH_MODE=env` (default) — every session uses the `RAD_SECURITY_*` environment credentials. Single-tenant, and **unauthenticated at the HTTP layer**, so it must not be reachable from untrusted networks.
-- `MCP_AUTH_MODE=header` — every request must carry its own credential in the `Authorization` header (the `Bearer <access_key_id>:<secret_key>:<account_id>` form above); a missing or malformed header is rejected with `401`. Only supported with `TRANSPORT_TYPE=streamable`. `RAD_SECURITY_API_URL` is taken from server config, not the caller.
-
-```bash
-docker run \
-  -e TRANSPORT_TYPE=streamable \
-  -e MCP_AUTH_MODE=header \
-  -e RAD_SECURITY_API_URL=https://api.rad.security \
-  -p 3000:3000 \
-  rad-security/mcp-server
-```
-
-> The SSE transport (`TRANSPORT_TYPE=sse`) is deprecated in favor of Streamable HTTP and uses env credentials only.
-
 ## Development
 
 ```bash

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.36-5.g3825a61";
+export declare const VERSION = "0.0.36";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "0.0.36-5.g3825a61";
+export const VERSION = "0.0.36";
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,mBAAmB,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rad-security/mcp-server",
-  "version": "0.0.36-5.g3825a61",
+  "version": "0.0.36",
   "description": "RAD Security MCP Server for AI-powered security insights",
   "type": "module",
   "main": "dist/index.js",