---
title: "AI - Workshop Docs"
description: "AI - Enterprise control plane for Santa. Manage rules, approvals, telemetry, and policies across your macOS fleet."
doc_version: "1"
last_updated: "2026-09-11"
canonical: "https://northpole.security/docs/workshop/ai"
---
# 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

### 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](https://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

#### 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](https://claude.ai/download)
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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for more details.

#### Claude Code

1.  **Install Claude Code** from [claude.ai](https://claude.ai/download)
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](https://docs.anthropic.com/en/docs/claude-code/mcp) for more details.

#### LM Studio

1.  **Install LM Studio** from [lmstudio.ai](https://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](https://lmstudio.ai/docs/app/mcp) for more details.

#### Gemini CLI

1.  **Install Gemini CLI** from [github.com/google-gemini/gemini-cli](https://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](https://geminicli.com/docs/tools/mcp-server/) 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:

Header

Effect

`X-MCP-Toolsets`

Comma-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-Tools`

Comma-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-Readonly`

Narrows 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 param

Equivalent header

Example

`toolsets`

`X-MCP-Toolsets`

`/mcp?toolsets=risk_engine,hosts`

`tools`

`X-MCP-Tools`

`/mcp?tools=list_rules,create_rule`

`readonly`

`X-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.

### 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?

## Sitemap

- [Home](https://northpole.security/index.md)
- [Workshop](https://northpole.security/workshop.md)
- [Santa](https://northpole.security/santa.md)
- [Features](https://northpole.security/features.md)
- [Cookbook](https://northpole.security/cookbook.md)
- [Docs](https://northpole.security/docs.md)
- [Blog](https://northpole.security/blog.md)
- [Glossary](https://northpole.security/glossary.md)
- [About](https://northpole.security/about.md)
- [Contact](https://northpole.security/contact.md)