A
licenseNot graded
qualityF
maintenanceA read-only MCP server that exposes Quickwit log search and aggregations to LLM clients, enabling natural language log investigation.
Apache 2.0
csw-mcp
by chandrapati
A read-only MCP server that lets you ask plain-English questions about a Cisco Secure Workload (Tetration) cluster from any stdio MCP client (Cursor, Claude Code, Codex, LM Studio), returning answers instead of raw API calls.
Inventory & scopes — list the scope tree, enumerate agents/sensors with hostnames, platforms and IPs, search inventory by field/value, and fetch a single workload by IP.
Cluster posture — headline KPIs: total agents, enforcing vs. visibility-only, and enforcement coverage percentage.
Policy visibility — list workspaces, show a workspace's policies, see what policies apply to a given workload, and audit ALLOW policies that open risky ports (RDP/SMB/etc.).
Flows & ADM — search recent flows over a time window, pull ADM conversations per workspace, rank risky-port exposure, summarize verdicts/ports/processes, and spot long-lived processes.
Vulnerabilities — list CVEs and installed packages for a workload, with severity tallies, and rank the most vulnerable hosts (critical×10 + high).
Forensics — list forensic profiles, detection rules (with MITRE IDs), and which profile is bound to which agent group.
Cluster integrations & config — inventory filters, connectors, orchestrators (credentials stripped), Secure Connector tunnel status, agent config profiles, and API roles.
Resources — cluster info, cached scope hierarchy, latest local snapshot, and latest executive-summary report.
Prompts — prebuilt workflows: blast-radius triage, weekly posture review, POV closeout.
Safety — GET and read-only search POSTs only (no create/update/delete), local stdio transport, bounded/retried queries, and credentials loaded from a git-ignored
.env.
Read-only querying of a Cisco Secure Workload (CSW/Tetration) cluster — inspects scopes, agents/sensors and their enforcement vs. visibility mode, workspaces and policies, inventory workloads, observed network flows and ADM conversations, plus workload CVEs, installed packages and forensic profiles. Includes posture aggregators such as cluster posture KPIs, risky-service exposure ranking (RDP/SMB/telnet/DB ports), and host ranking by CVE severity.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@csw-mcp how many agents are enforcing policy?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
csw-mcp
Query Cisco Secure Workload in natural language — a read-only MCP server for any client that can launch a local stdio server, including Cursor, Claude Code, Codex, and LM Studio.
Ask “how many agents are enforcing policy?” or “which hosts have exploitable critical CVEs?” — and get an answer, not an API call.
What it is
csw-mcp is a Model Context Protocol server
that lets an MCP client (Cursor, Claude Code, Codex, LM Studio, or any other stdio host) query a Cisco Secure Workload
(CSW / Tetration) cluster in plain English. It is for anyone who wants to
use CSW and get posture answers without writing HMAC-signed API calls.
flowchart TB
ui["1 · In the Secure Workload UI<br/>User Menu → API Keys → Create API Key"]
env["2 · On your laptop, copy .env.example to .env<br/>CSW_API_URL · CSW_API_KEY · CSW_API_SECRET"]
ask["3 · Ask in Cursor, Claude Code,<br/>Codex, or LM Studio"]
local["4 · csw-mcp reads that .env<br/>and signs each call with the API secret"]
tenant["5 · Your Secure Workload tenant"]
reply["6 · The answer comes back in the chat"]
ui --> env --> ask --> local
local -->|"read-only, no OAuth"| tenant
tenant -->|"scopes · agents · workspaces<br/>inventory · forensic profiles"| reply
classDef step fill:#F8FAFC,stroke:#005073,color:#020617;
classDef cred fill:#FFFBEB,stroke:#d97706,color:#020617;
classDef cisco fill:#00bceb,stroke:#005073,color:#ffffff;
class ask,local,reply step;
class ui,env cred;
class tenant cisco;Where the cluster info goes: a file named .env in this repo (it stays on your machine and is never committed). No OAuth, no browser login, and no extra token service. Secure Workload uses an API key plus its matching secret. Create that pair in the product UI under User Menu → API Keys → Create API Key, then put these three lines in .env:
CSW_API_URL=https://your-cluster.tetrationcloud.com
CSW_API_KEY=your_api_key_here
CSW_API_SECRET=your_api_secret_hereCSW_API_URL is the cluster address only, with no path on the end. The key needs read access for sensors, flows, and policy. Setup steps are in docs/INSTALL.md.
Start with one of these. They are the current capabilities confirmed on a live tenant:
“Show me the scope tree.”
“List the agents on this cluster.”
“What workspaces are defined?”
“Find the workload for this IP.”
“Which forensic profiles are on this cluster?”
The server only reads. It does not create, change, or delete anything on the tenant, and it listens only on a local stdio pipe. If a read does not come back the first time, the server waits briefly and tries again a few times so the data still arrives. The HMAC signing and module layout are in docs/ARCHITECTURE.md.
This repo is companion tooling, not official Cisco documentation. Confirm behavior against your cluster's in-product help and the Cisco Secure Workload product documentation.
Related MCP server: MSSQL-MCP
New to Cisco Secure Workload?
Cisco Secure Workload (also called Tetration) watches how servers talk to each other, then lets you write firewall-style rules that follow the workload instead of a fixed IP. The goal is simple: if one machine is compromised, the attacker should not be able to walk sideways to the next one. That is micro-segmentation, and the size of the damage an attacker can do is the blast radius.
You do not need to know the product to use this server. Ask a question in English. The model calls the tools below and answers in plain language.
Term you will see | Plain meaning |
Agent / sensor | Software on a host that reports connections. In enforcement mode it also blocks traffic the policy does not allow. In visibility mode it only watches. |
Scope | A folder in the inventory tree (for example Production, Databases, WebTier) used to group workloads and attach policy. |
Workspace / application | A policy container. ADM (Application Dependency Mapping) looks at real traffic and proposes a starter ruleset. |
Flow | One observed connection: who talked to whom, on which port, and whether policy allowed it. |
Conversation | A summarized "these two groups talk on this port" pair that ADM uses to draft policy. |
Workload | One host, VM, or pod that CSW is tracking. |
If you want the longer story — why this exists, how a POV is run, and a video learning path — start with CSW User Education.
Quickstart
# 1. Enter the repo
cd csw-mcp
# 2. Create the environment and install (uv — https://astral.sh/uv)
uv venv
uv pip install -e .
# 3. Configure credentials
cp .env.example .env # then edit with your cluster URL / key / secret
# 4. Register with a client. Cursor:
bash scripts/install-cursor.sh
# Claude Code, Codex, and LM Studio: see docs/INSTALL.md
# 5. Reload that client, then ask: "Summarize my CSW cluster posture."Verify it loaded:
uv run python -c "from csw_mcp.server import mcp; print('tools:', len(mcp._tool_manager._tools), 'prompts:', len(mcp._prompt_manager._prompts))"
# tools: 26 prompts: 3
# Optional: smoke-test every tool against your own cluster
uv run python tests/test_tools_live.pyFull step-by-step with screenshots-as-ascii: docs/INSTALL.md.
Capabilities
Tools (26)
Name | What it does |
| List the scope hierarchy ( |
| List agents/sensors (uuid, hostname, agent_type, platform, IPs) |
| Search inventory by field/value filter |
| Fetch one workload's inventory record by IP |
| Headline posture KPIs (enforcement coverage, agents by type) |
| List application workspaces (policy folders / ADM scopes) |
| List policies defined in a workspace |
| List policies currently applied to a workload |
| Search network flows over a recent time window |
| List ADM conversations (talker pairs) for a workspace |
| Rank risky-service exposure (RDP/SMB/telnet/DB ports) |
| List CVEs on a workload + severity tally |
| List installed packages on a workload |
| Rank hosts by CVE severity (critical×10 + high) |
| List configured forensic profiles |
| Forensic detection rules, with MITRE ids taken from the rule name |
| Which forensic profile is bound to which agent group |
| Policy verdicts, busiest ports, and process names in a flow sample |
| Processes that keep appearing across daily flow samples |
| ALLOW policies that open a risky management or data port |
| Inventory filters ( |
| Connectors for the root scope ( |
| Orchestrators in the root scope, with cloud credentials removed |
| Whether the root-scope Secure Connector tunnel is active |
| Software agent configuration profiles |
| API roles and capability flags (not the user directory) |
Resources (4)
URI | What it does |
| Cluster URL, config state, quick scope/agent counts |
| Scope hierarchy (cached ~60s) |
| Newest local |
| Newest local executive-summary markdown |
Prompts (3)
csw/triage-blast-radius · csw/weekly-posture-review · csw/pov-closeout
See docs/USAGE.md for example prompts and when to use each tool.
Current capabilities
Confirmed on a live SaaS tenant. Each row below returned data. Full notes: docs/TESTED.md.
Feature | What you get | Try this | |
✅ |
| The scope tree | “Show me the scope tree.” |
✅ |
| Agents, hostnames, platforms, addresses | “List the agents on this cluster.” |
✅ |
| Application workspaces | “What workspaces are defined?” |
✅ |
| Inventory matches for an IP or field | “Find the workload for this IP.” |
✅ |
| One workload record | “Show me the workload at this IP.” |
✅ |
| Configured forensic profiles | “Which forensic profiles are on this cluster?” |
✅ |
| Agent count, scope count, and enforcement coverage | “How many agents are enforcing?” |
✅ |
| Absolute and default policies for a workspace | “Show the policies in this workspace.” |
✅ |
| Recent flows in a scope | “Show recent flows in the root scope.” |
✅ |
| ADM conversations for a workspace | “Show the conversations for this workspace.” |
✅ |
| Risky ports with recent flow activity | “Which risky ports have recent traffic?” |
✅ |
| Forensic detection rules, including MITRE ids in the name | “Which forensic rules are configured?” |
✅ |
| Which profile is bound to which agent group | “Which forensic profile applies where?” |
✅ |
| Policy verdicts, busiest ports, and process names in a sample | “Summarize recent flows.” |
✅ |
| Processes that keep appearing across daily samples | “Which processes stay up across days?” |
✅ |
| ALLOW policies that open a risky port | “Which policies allow RDP or SMB?” |
✅ |
| Inventory filters | “List the inventory filters.” |
✅ |
| Connectors on the root scope | “Which connectors are configured?” |
✅ |
| Orchestrator name and type, credentials removed | “Which orchestrators are on this cluster?” |
✅ |
| Whether the Secure Connector tunnel is active | “Is the Secure Connector up?” |
✅ |
| Agent configuration profiles | “Which agent config profiles exist?” |
✅ |
| API roles | “Which roles are defined?” |
Examples
Five fully-synthetic walkthroughs live in examples/, each with
a question, the tool-call flow, and a rendered HTML deliverable:
blast-radius-triage— "Which hosts aren't enforcing?"executive-summary— "One-page CISO summary."cve-prioritization— "Exploitable + exposed CVEs?"weekly-posture-review— "What changed since last week?"pov-closeout— "Closeout + 30-day plan."
Configuration
Credentials come from a project-level .env (never committed — see .gitignore):
Variable | Required | Notes |
| yes | Cluster base URL, no trailing slash |
| yes | API key (hex) from CSW UI → API Keys |
| yes | HMAC signing secret paired with the key |
| no | Set |
| no | Explicit path to an alternate env file |
| no | Path to a CSW_POV_Template checkout (enables snapshot/report resources) |
Generate an API key in the CSW UI (User Menu → API Keys → Create API Key) with
read capabilities: sensor_management, flow_inventory_query, app_policy_management.
Safety & design principles
Read-only. Only GET and read-only search POSTs; no create/update/delete tools.
stdio transport. No listening socket → no DNS-rebinding / CSRF surface.
Single-purpose tools. No "run arbitrary request" escape hatch.
Bounded. Result limits are clamped; aggregators cap fan-out and pagination.
Retries. A read that does not come back the first time is tried again a few times, with a short wait between tries, so the data still arrives.
No secrets in code. Credentials load from a git-ignored
.env; nothing is logged.Minimal output. Tool results are projected to the fields you need.
More detail: docs/ARCHITECTURE.md.
Documentation
Doc | Contents |
Full install, wiring, verification | |
Example prompts, tool selection, combining tools | |
Top 10 "it broke" fixes | |
How to add a new tool (+ test) | |
Components, modules, HMAC auth flow |
Development
The CSW API client (src/csw_mcp/vendor/csw_api.py, csw_helpers.py) is
vendored from the generic CSW_POV_Template project and should not be edited
by hand. Re-sync it with:
CSW_POV_TEMPLATE=/path/to/CSW_POV_Template bash scripts/sync-vendor.shRegenerate the example reports:
python3 examples/build_examples.pyRelated CSW material
Same author, public repos. Use these when you want the background, a POV plan, or the script toolkit this server sits on top of. Customer-specific repos are intentionally not listed here.
Learn the product
Repo | Use it when you want… |
A plain-language intro, video library, and onboarding path | |
A field guide any SE can run: scope, observe, model policy, enforce safely, executive readout | |
Who shows up in a deal, what they care about, and which CSW topics to lead with | |
Official Secure Workload documentation |
Query and report on a cluster
Repo | How it relates to csw-mcp |
The Python scripts (snapshots, flows, policies, HTML reports) whose API client this server vendors. Use the scripts for batch reports; use csw-mcp to ask questions in chat. | |
Reads an agent diagnostic log bundle (enforcement timing, policy versions) — a different input than the live API this server calls. | |
How CSW controls map to HIPAA, SOC 2, PCI DSS, NIST 800-53, ISO 27001, and related frameworks | |
A visual companion to the |
Install agents and connect other systems
Repo | Topic |
Install the agent on cluster nodes and enforce pod/service policy | |
Connector labels, DaemonSet, container CVE scanning | |
Same pattern, plus the privileged SCC OpenShift requires | |
Deploy the on-prem virtual cluster (OVA, site config, hardening) | |
Host policy plus firewall (NSEL) visibility | |
Inventory enrichment labels from ServiceNow | |
Align CSW scopes with ACI EPGs |
License
Available Tools
15 toolsget_conversationsA
List ADM conversations (observed talker pairs) for a workspace.
Args:
app_id: The workspace/application id (from list_workspaces).
version: Optional ADM version; omit for the latest.
Reads GET /openapi/v1/conversations/{app_id}, paginating up to a safety cap.
Conversations are the raw src→dst:port pairs ADM used to propose policy.
Inputs: app_id (required), version. Returns: result
get_workloadA
Fetch the inventory record for a single workload by IP address.
Looks up the workload via a read-only inventory search for the exact IP. Returns the full record if found, or a graceful not-found message. Use this to inspect one host's annotations, scopes, and attributes.
Inputs: address (required). Returns: result
get_workload_cvesA
List CVEs / vulnerabilities detected on a single workload.
Args:
uuid: The workload/sensor UUID (from list_sensors).
Returns records from GET /openapi/v1/workload/{uuid}/vulnerabilities plus a
severity tally (critical/high/medium/low).
Inputs: uuid (required). Returns: result
get_workload_packagesA
List installed software packages on a single workload.
Args:
uuid: The workload/sensor UUID (from list_sensors).
Returns records from GET /openapi/v1/workload/{uuid}/packages.
Inputs: uuid (required). Returns: result
get_workspace_policiesA
List the policies defined in a workspace.
Args:
app_id: The workspace/application id (from list_workspaces).
Returns the policy records from
GET /openapi/v1/applications/{app_id}/policies.
Inputs: app_id (required). Returns: result
list_forensic_profilesB
List configured forensic profiles (behavioral rule sets for agents).
Returns records from GET /openapi/v1/inventory_config/forensic_profiles.
Inputs: no named parameters. Returns: result
list_policies_for_workloadA
List the policies that currently apply to a single workload.
Args:
uuid: The workload/sensor UUID (from list_sensors).
Returns the policies from GET /openapi/v1/workload/{uuid}/policies — useful
to understand exactly what a given host is allowed to talk to.
Inputs: uuid (required). Returns: result
list_scopesA
List the CSW scopes (the hierarchy that organizes workloads and policy).
Returns a count and the raw scope records from GET /openapi/v1/app_scopes.
Use this to understand how the cluster is segmented before drilling in.
Inputs: no named parameters. Returns: result
list_sensorsA
List the agents/sensors registered on the cluster (summarized).
Each entry includes uuid, hostname, agent_type (ENFORCER / VISIBILITY / …),
platform, and the host's IPs. limit caps how many records are returned
(1–1000). Use this to inventory the fleet and spot which hosts run an
enforcing agent vs. visibility-only.
Inputs: limit. Returns: result
list_workspacesA
List application workspaces (policy folders / ADM scopes).
Returns the workspaces from GET /openapi/v1/applications. Each workspace
groups policy rules and ADM versions. Use the returned id with
get_workspace_policies or get_conversations.
Inputs: no named parameters. Returns: result
search_flowsA
Search network flows over a recent time window.
Args: filter_json: A CSW flow filter as a JSON string, e.g. '{"type":"eq","field":"dst_port","value":3389}'. Pass an empty string for no filter (all flows in the window). hours: Look-back window in hours (1–720, default 24). limit: Max flow records to return (1–1000).
Runs a read-only POST /openapi/v1/flowsearch with t0 = now-hours, t1 = now.
Inputs: hours, limit, filter_json. Returns: result
search_inventoryA
Search cluster inventory for workloads matching a field/value filter.
Args: value: The value to match (e.g. an IP, hostname fragment, OS string). field: The inventory dimension to filter on (default "ip"). Common fields: "ip", "hostname", "os", "user_annotations". match: CSW filter operator — "eq" (exact), "contains", "subnet", etc. Defaults to "eq". limit: Max results to return (1–1000).
Runs a read-only POST /openapi/v1/inventory/search. Returns a count and
the matching inventory records.
Inputs: value (required), field, limit, match. Returns: result
summarize_cluster_postureA
Summarize the cluster's security posture at a glance.
Returns headline KPIs for a security-leadership audience: total agents, how many are enforcing policy vs. visibility-only, the enforcement coverage percentage, and a breakdown of agents by type. This is the fastest way to gauge blast-radius exposure.
Inputs: no named parameters. Returns: result
top_risky_flowsA
Rank risky-service exposure by counting recent flows to sensitive ports.
Scans the last hours for flows to high-risk management/data ports (RDP,
SMB, telnet, MSSQL, MySQL, PostgreSQL, Redis, MongoDB) and returns the ports
with the most observed flows. A fast way to spot lateral-movement surface.
Args: hours: Look-back window in hours (1–720, default 24). limit: Max flow samples to inspect per port (1–1000).
Inputs: hours, limit. Returns: result
top_vulnerable_hostsA
Rank the most vulnerable hosts in the cluster by CVE severity.
Iterates sensors, pulls each host's vulnerabilities, and scores them as
(critical * 10 + high). Returns the top limit hosts with their CVE counts.
Scanning is capped for safety on large clusters.
Args: limit: Number of top hosts to return (1–1000).
Inputs: limit. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
A3.7/5.0
Scored across 15 tools
Disambiguation4/5
Each tool targets a distinct resource or action, with clear separation between inventory, policy, flow, and vulnerability queries. Minor overlap exists between get_workload and search_inventory for single-host lookup, and between list_scopes and list_workspaces as hierarchical grouping concepts, but descriptions clarify their boundaries.
Naming Consistency4/5
All tool names use snake_case and generally follow a verb_noun pattern (list_, get_, search_, summarize_). The ranking tools top_risky_flows and top_vulnerable_hosts deviate slightly with a top_ prefix, but remain readable and consistent with each other.
Tool Count5/5
Fifteen tools is within the well-scoped range and each covers a distinct facet of the CSW domain: inventory, sensors, scopes, policies, flows, vulnerabilities, and forensic profiles. No tool appears redundant or unnecessary for the breadth of surface presented.
Completeness3/5
The surface is entirely read-only, offering broad coverage for analysis and posture assessment but no create/update/delete operations for policies, workspaces, scopes, sensors, or forensic profiles. This is a notable lifecycle gap that will prevent agents from performing management actions through this MCP.
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues
Related MCP Connectors
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Related MCP Servers
- AlicenseAqualityCmaintenanceSecurity-first, read-only MCP server for Microsoft SQL Server, enabling safe natural-language querying of databases.57 npmMIT
- AlicenseAqualityDmaintenanceA read-only MCP server that enables AI assistants to query ServiceNow instances—incidents, changes, users, CMDB—with malformed query linting and injection protection.7MIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server for Cisco Meraki Dashboard, enabling LLMs to discover devices, check health, troubleshoot, and generate reports via natural language.MIT