Skip to main content

AI

Workshop provides AI-powered features to help you manage and understand your endpoint security environment.

AI Chat​

AI Chat lets you ask natural-language questions about your Workshop data directly from the dashboard. Chat sessions have the same permissions as the logged-in user — the AI assistant can only access data you're authorized to see.

Setup​

  1. Go to Settings → AI → Chat
  2. Toggle Enabled
  3. Select an AI provider (Anthropic, OpenAI, or Google)
  4. Enter your API key for the chosen provider
  5. Optionally select a specific model (defaults are recommended)

Privacy​

warning

Information you send to AI Chat — including your questions, conversation history, and any Workshop data retrieved by the assistant — is sent to whichever third-party AI provider your organization has configured. Review your provider's data handling policies before enabling AI Chat.

Supported Providers​

  • Anthropic
  • OpenAI
  • Google

What You Can Do​

AI Chat can query your Workshop data using the same API methods available through the web interface. Example questions:

Show me a summary of all rules in Workshop.

Why is <app name> blocked on <host name>?

What are the top 10 most executed applications across my fleet?

Are any of my hosts out of date?

The assistant uses tools to look up data, perform calculations, and query Workshop documentation. By default, the assistant cannot modify your configuration. To enable write access, toggle Read-Write Mode in AI Chat settings.

MCP Server​

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to large language models (LLMs). Learn more at modelcontextprotocol.io.

Workshop's MCP server exposes all of the methods available in the Workshop API to MCP-compatible clients such as Claude Desktop, Claude Code, LM Studio, and Gemini CLI.

Getting Started​

1. Enable the MCP Server​

  1. Go to Settings → AI → MCP
  2. Toggle the switch to enable the MCP server
warning

By default the MCP server only allows read-only access, even if you have added write permissions to the API key or OAuth scope. You must enable read-write mode in the MCP settings to allow MCP clients to make changes.

2. Choose an Authentication Method​

OAuth 2.0 (recommended): MCP clients that support OAuth will automatically prompt you to log in — no extra setup needed. Just point the client at your Workshop MCP URL and authenticate through the browser.

API key (alternative): If your MCP client doesn't support OAuth, or you prefer key-based auth, generate an API key:

  1. Go to Settings → API Keys
  2. Click "Create API Key"
  3. Copy the key (it starts with npsws_sk_)

Authentication​

OAuth 2.0​

MCP clients that support OAuth 2.0 can authenticate using your organization's identity provider. This is the recommended approach. OAuth users receive permissions based on their Workshop role assignment. The MCP read-write toggle in settings provides an additional layer of control over write access.

API Key​

Alternatively, create an API key with the desired permissions and pass it in the Authorization header. See Choose an Authentication Method above.

Integrating with MCP​

Claude Desktop​

  1. Install Claude Desktop from claude.ai
  2. Open Settings → Connectors
  3. Click Add custom connector
  4. Enter your Workshop MCP URL: https://example.workshop.cloud/mcp
  5. Click Add — Claude will open a browser window for OAuth authentication

See the Claude custom connectors documentation for more details.

Claude Code​

  1. Install Claude Code from claude.ai
  2. Run the following command to add the Workshop MCP server:
claude mcp add --transport http workshop https://example.workshop.cloud/mcp

Claude Code will open a browser window for OAuth authentication when you first connect. See the Claude Code MCP documentation for more details.

LM Studio​

  1. Install LM Studio from lmstudio.ai
  2. Open the Program tab in the right sidebar
  3. Click Install → Edit mcp.json and add:
{
	"mcpServers": {
		"workshop": {
			"url": "https://example.workshop.cloud/mcp",
			"headers": {
				"Authorization": "npsws_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
			}
		}
	}
}

As of March 2026, LM Studio does not support OAuth for remote MCP servers, so an API key is required. See the LM Studio MCP documentation for more details.

Gemini CLI​

  1. Install Gemini CLI from github.com/google-gemini/gemini-cli
  2. Run the following command to add the Workshop MCP server:
gemini mcp add --transport http workshop https://example.workshop.cloud/mcp

See the Gemini CLI MCP documentation for more details.

Per-connection tool selection​

By default, every connection sees the same three tools: list_operations, describe_operation, and call_operation. The model calls list_operations to discover what it can do, describe_operation to learn an operation's request shape, then call_operation to invoke it.

A connection can opt into a different surface instead: one MCP tool per Workshop API operation, each with its own name and JSON schema. This is useful for clients that approve tool calls one tool at a time — call_operation is too generic a target for that kind of review, since it can invoke anything the caller is permitted to.

Configure the surface per connection with request headers, no server-side setting required:

HeaderEffect
X-MCP-ToolsetsComma-separated toolset slugs to expose as individual tools, or all for every operation. Setting this switches the connection to the individual-tool surface. An unknown slug returns 400 Bad Request.
X-MCP-ToolsComma-separated allowlist of individual tool names (e.g. list_rules,create_rule). Also switches the connection to the individual-tool surface. Names that aren't individual tools — unknown names, or the list_operations/describe_operation/call_operation trio and _Documentation — return 400 Bad Request.
X-MCP-ReadonlyNarrows this connection to read-only tools. Enabled by any value other than false, 0, or empty; disabled by omitting the header (or setting it to false or 0). Narrows only: if the workspace's MCP setting is read-only, this header cannot grant write access back — the workspace read/write setting is always the ceiling.

A toolset slug is an operation's group in lowercase, with underscores in place of spaces, so "Risk Engine" is risk_engine. The full set of toolset slugs:

administration, ai_chat, api_keys, approvals, audit, binary_uploads, blockables,
dashboard, directory, event_export, events, execution_rules, file_access_rules,
hosts, logs, mcp, mpa, network_flow_rules, package_rules, passkeys, reports,
risk_engine, roles, rule_packs, signals, slack, sync_auth, sync_settings, tags,
telemetry, webhooks

The server matches slugs exactly, so Risk_Engine fails. The 400 for an unknown slug names every valid one.

all isn't a group. It selects every operation, more than 150 tools, and it beats any narrower slug: toolsets=all,hosts equals toolsets=all. Reach for it when you want per-tool approval and schemas rather than a smaller surface, since every definition ships in the client's tool list and costs context whether the model calls it or not.

X-MCP-Tools takes tool names, not slugs: an operation's name in snake_case, so ListRules is list_rules.

Configure a connection​

Individual-tool mode hides list_operations, so pick your groups and names on a default connection first:

  1. Connect with no X-MCP-* config.
  2. Call list_operations. Each entry's group becomes a slug, its operation becomes a snake_case tool name.
  3. Reconnect with X-MCP-Toolsets or X-MCP-Tools set, alongside your existing auth.

Or in the URL:

https://example.workshop.cloud/mcp?toolsets=hosts,execution_rules&readonly=true

Any MCP client that lets you attach custom HTTP headers to the connection can use these. The server reads the headers, so there is nothing to turn on in the client beyond passing them through. Clients that support custom headers on a remote HTTP MCP server include VS Code (GitHub Copilot), Cursor, Claude Code, Windsurf, Continue.dev, and LM Studio (see its mcp.json example above). The field name varies by client (Windsurf uses serverUrl for the URL, Claude Code takes a --header flag, and Continue.dev nests headers under requestOptions), so follow each client's own MCP config format.

For clients that can only configure a bare URL — no custom headers — the same options are available as query params on the MCP endpoint:

Query paramEquivalent headerExample
toolsetsX-MCP-Toolsets/mcp?toolsets=risk_engine,hosts
toolsX-MCP-Tools/mcp?tools=list_rules,create_rule
readonlyX-MCP-Readonly/mcp?readonly=true

Each query param takes the same comma-separated value and follows the same rules as its header. The two sources — headers and query params — are additive: their toolset and tool lists combine, and the connection is read-only if either source requests it. Prefer headers where you can set them, since query params can appear in proxy and server access logs; the tool and toolset names here aren't sensitive, and your credentials always travel in the Authorization header regardless.

note

Selecting either surface switches the connection to individual-tool mode, which hides the list_operations/describe_operation/call_operation trio — including call_operation — so a client can't dispatch an arbitrary operation through it and bypass the per-tool approval that individual tools exist to enable. Read-only tools declare an MCP readOnlyHint annotation, so HITL clients can use it to auto-approve reads.

Telemetry queries​

QueryTelemetry — exposed as query_telemetry on the individual-tool surface and as call_operation("QueryTelemetry") on the default one — streams results from the telemetry store and hands the model a single tool result. Three limits shape what comes back:

  • Results truncate at 64 KB. Rows are cut at a row boundary once the result reaches 64 KB. The result then carries "truncated": true and a guidance field telling the model to narrow the query with LIMIT, a time-range filter, or aggregation, or to reduce the column count when rows are wide.
  • A call has 240 seconds on MCP and 90 seconds in AI chat. A chat turn runs tool calls one after another inside a single request, so chat gets the smaller budget. Past the limit, a query that has produced rows returns them marked truncated, and one that has produced none returns a deadline_exceeded error. Both are self-correctable: narrow the query and try again.
  • Keep-alives depend on the client. While a slow query runs, the server emits an MCP notifications/progress message for each batch of rows and each 15-second heartbeat — but only if the client sent a progressToken with the tool call. A client that sends no token receives nothing until the query finishes, so its own tool-call timeout decides how long it waits.

Example Prompts​

Show me a summary of all rules in Workshop and use terms from the documentation to explain them.

Why is <app name> blocked on <host name> in Workshop?

Are any of my Workshop hosts out of date?

Are my Workshop hosts ready to switch from Monitor Mode to Lockdown Mode?