@rad-security/mcp-server 0.0.36 → 0.0.37

package/README.md

@@ -8,225 +8,212 @@ 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>
 
-## Installation
+## Connect (hosted — recommended)
 
-```bash
-npm install @rad-security/mcp-server
-```
-
-## Usage
+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.
 
-### Prerequisites
-
-- Node.js 20.x or higher
+- **Endpoint:** `https://api.rad.security/mcp/` — note the **trailing slash**.
+- **Transport:** Streamable HTTP.
+- **Authentication:** send your credential in the `Authorization` header:
 
-### Environment Variables
+  ```
+  Authorization: Bearer <access_key_id>:<secret_key>:<account_id>
+  ```
 
-The following environment variables are required to use the MCP server with Rad Security:
+  `<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.
 
-```bash
-RAD_SECURITY_ACCESS_KEY_ID="your_access_key"
-RAD_SECURITY_SECRET_KEY="your_secret_key"
-RAD_SECURITY_ACCOUNT_ID="your_account_id"
-```
+> 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).
 
-Optional environment variables:
+### Claude Code
 
 ```bash
-RAD_SECURITY_TENANT_ID="your_tenant_id"  # Optional: If not provided, will be fetched automatically from the account
+claude mcp add --transport http rad-security https://api.rad.security/mcp/ \
+  --header "Authorization: Bearer <access_key_id>:<secret_key>:<account_id>"
 ```
 
-#### Optional: Filter Toolkits
-
-You can control which toolkits are exposed by the MCP server using these environment variables:
+### OpenAI Codex CLI
 
-- `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)
-
-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
-
-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:
+`~/.codex/config.toml`:
 
+```toml
+[mcp_servers.rad-security]
+url = "https://api.rad.security/mcp/"
+http_headers = { "Authorization" = "Bearer <access_key_id>:<secret_key>:<account_id>" }
 ```
-Authorization: Bearer <access_key_id>:<secret_key>:<account_id>
-Authorization: Bearer ory_st_<session_token>:<account_id>
-```
-
-`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.
-
-> **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.
 
-Examples:
+Or via the CLI, keeping the secret in an env var (`export RAD_MCP_TOKEN=<access_key_id>:<secret_key>:<account_id>`):
 
 ```bash
-# Only enable workflow toolkit
-INCLUDE_TOOLKITS="workflows"
+codex mcp add rad-security --url https://api.rad.security/mcp/ --bearer-token-env-var RAD_MCP_TOKEN
+```
 
-# Enable only containers and images toolkits
-INCLUDE_TOOLKITS="containers,images"
+### Cursor
 
-# Exclude workflow toolkit (enable all others)
-EXCLUDE_TOOLKITS="workflows"
+`.cursor/mcp.json`:
 
-# Exclude runtime toolkit
-EXCLUDE_TOOLKITS="runtime"
+```json
+{
+  "mcpServers": {
+    "rad-security": {
+      "type": "http",
+      "url": "https://api.rad.security/mcp/",
+      "headers": {
+        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
+      }
+    }
+  }
+}
 ```
 
-Note: If `INCLUDE_TOOLKITS` is set, `EXCLUDE_TOOLKITS` is ignored.
+### VS Code (GitHub Copilot)
 
-### In cursor IDE
+`.vscode/mcp.json` — note the wrapper key is `servers`, not `mcpServers`:
 
-It's quite problematic to set ENV variables in cursor IDE.
+```json
+{
+  "servers": {
+    "rad-security": {
+      "type": "http",
+      "url": "https://api.rad.security/mcp/",
+      "headers": {
+        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
+      }
+    }
+  }
+}
+```
 
-So, you can use the following start.sh script to start the server.
+### Gemini CLI
 
-```bash
-./start.sh
-```
+`~/.gemini/settings.json` — note the URL field is `httpUrl` (not `url`):
 
-Please set the ENV variables in the start.sh script first!
+```json
+{
+  "mcpServers": {
+    "rad-security": {
+      "httpUrl": "https://api.rad.security/mcp/",
+      "headers": {
+        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
+      }
+    }
+  }
+}
+```
 
-### In Claude Desktop
+### Cline
 
-You can use the following config to start the server in Claude Desktop.
+`cline_mcp_settings.json` — note `type` must be exactly `streamableHttp` (camelCase):
 
 ```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>"
+      "type": "streamableHttp",
+      "url": "https://api.rad.security/mcp/",
+      "headers": {
+        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
       }
     }
   }
 }
 ```
 
-To filter toolkits, add `INCLUDE_TOOLKITS` or `EXCLUDE_TOOLKITS` to the env:
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json` — note the URL field is `serverUrl`:
 
 ```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>",
-        "EXCLUDE_TOOLKITS": "workflows"
+      "serverUrl": "https://api.rad.security/mcp/",
+      "headers": {
+        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
       }
     }
   }
+}
 ```
 
-### As a Docker Container - with Streamable HTTP
+### Other clients
 
-```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
-```
+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.
 
-With toolkit filters:
+| 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 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.ai / Claude Desktop / Claude Tag (Slack)
+
+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:
 
-### As a Docker Container - multi-tenant (per-request auth)
+- **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).
 
-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.
+### Test it (MCP Inspector or curl)
 
 ```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
+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>" }
 ```
 
-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 http://localhost:3000/mcp -d '{...}'
+  -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"}}}'
 ```
 
-### As a Docker Container - with SSE (deprecated)
+### 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.
 
-*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.
+| 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`:
 
 ```bash
-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
+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"
 ```
 
 ## Features
 
-All tools require authentication and an account in Rad Security.
+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.
 
 - Account Inventory
   - List clusters and their details
@@ -286,6 +273,93 @@ All tools require authentication and an account in Rad Security.
   - 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";
+export declare const VERSION = "0.0.37";

package/dist/version.js

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

package/package.json

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