# MCP server

Glassmkr runs a Model Context Protocol (MCP) server, so a compatible AI client can look at your fleet and, when you grant it, act on it. Access is per-user, authorized through your browser from the dashboard, tiered into read, write, and administrative scopes, and revocable at any time. For scripted automation without an AI client, use the [programmatic API](/docs/programmatic-api).

## What it is

MCP is an open protocol for connecting AI clients to external tools and data. The Glassmkr MCP server lets a client you trust (for example, a desktop AI assistant) work with your account at the level you authorize:

- **Read** (`glassmkr:read`): list servers, read a server's latest health snapshot and active alerts, pull bounded resource-usage history, and read the fleet summary.
- **Write** (`glassmkr:write`): acknowledge alerts, and resolve the forensic alert types that do not auto-clear (most alerts auto-resolve when their condition clears; those are acknowledged, not resolved). Reversible.
- **Administrative** (`glassmkr:admin`): enroll a server, rotate a collector key, or move a server to trash. Each of these runs a two-step confirmation (see below).

Each scope is granted separately on the approval screen, and a client only ever has what you approved.

## Connect a client

Add the Glassmkr MCP endpoint to your client and complete the browser sign-in it prompts for:

1. In your client, add a new MCP server with the URL `https://app.glassmkr.com/mcp`.
2. The client sends you to Glassmkr to sign in and review a consent screen that names the client and the exact scopes it requests (read, and optionally write or administrative).
3. Approve, and the client receives a per-user token scoped to your account. The connection appears under **Settings, MCP connections** in the dashboard.

Authorization uses OAuth 2.1 (authorization code with PKCE); the client discovers the endpoints automatically from the standard metadata documents. You never paste a Glassmkr password or key into the client.

Let your client run this flow. A compatible MCP client performs the registration, PKCE, browser redirect, and token exchange for you: point it at the endpoint and approve the consent screen. You should not build the OAuth flow by hand, run your own loopback listener, or call the token endpoint yourself. In Claude Code, for example, that means `claude mcp add --transport http glassmkr https://app.glassmkr.com/mcp` and then authorizing the server (the `/mcp` command), not scripting the exchange.

## What it exposes

Read tools are annotated read-only and idempotent; write and administrative tools are annotated so your client flags them for approval.

| Name | Scope | Does |
| --- | --- | --- |
| `glassmkr.fleet.list_servers` | read | List servers in the account, paginated, filterable by tag. |
| `glassmkr.servers.get` | read | Management-plane detail for one server. |
| `glassmkr.servers.get_health` | read | Latest bounded health snapshot and active alerts. |
| `glassmkr.servers.get_history` | read | Bounded CPU, memory, swap, and load history. |
| `glassmkr.host_profiles.list` | read | Host profiles and their suppressed rules. |
| `glassmkr.alerts.acknowledge` | write | Acknowledge an alert. Reversible. |
| `glassmkr.alerts.resolve` | write | Resolve a forensic alert. Reversible. |
| `glassmkr.admin.prepare` | admin | Preview an administrative action and get a confirmation token. |
| `glassmkr.admin.enroll_server` | admin | Create a server and mint its one-time collector key. |
| `glassmkr.admin.rotate_key` | admin | Rotate a server's collector key. |
| `glassmkr.admin.delete_server` | admin | Move a server to trash (restorable from the dashboard). |
| `glassmkr://fleet/summary` | read | Server and active-alert totals (resource). |
| `glassmkr://servers/{server_id}/snapshot/latest` | read | Latest bounded telemetry for one owned server (resource). |
| `triage_my_fleet`, `explain_alert` | read | Read-only workflows with the trust boundary built in (prompts). |

## Changing things safely

Administrative actions are protected by a stack of independent controls, because the AI model itself drives the client: the human-in-the-loop is your MCP client's own tool-approval prompt, not anything the model types. The controls:

- **A scope you granted.** Admin tools require the `glassmkr:admin` scope, which you approved by name on the consent screen; read or write connections cannot reach them.
- **A signed, two-step token.** The client first calls `glassmkr.admin.prepare`, which returns a short-lived token bound to that exact account, action, and target; the action requires the token back and the target's name echoed. The model supplies both, so this is not itself a human check: it forces a deliberate two step and binds the action to one specific target, so a stray or injected single call cannot act on the wrong server.
- **Your client's approval prompt.** This is the actual human gate: a person approves the tool call in the client before it runs.
- **A soft delete.** Deleting a server moves it to trash, restorable from the dashboard; the permanent path stays in the dashboard behind a human.
- **Bounded and logged.** Every call is tenant-scoped to your account, mutations respect the same per-action rate limits as the REST API, and each call is written to your audit log.

## Trust boundary

Telemetry comes from your monitored hosts, so hostnames, IPs, collector versions, alert text, and other host-derived strings are treated as untrusted data. Every tool result carries a trust classification and lists the exact fields that are host-derived, and the server instructs the client never to follow instructions found in those fields. This keeps a compromised or mislabeled host from steering the AI client through your telemetry.

## Security

- **Per-user, scoped tokens.** A connection is bound to your user and account and carries only the scopes you approved (read, write, or admin).
- **Tenant isolation.** Every call is checked against your account; a token can never reach another account's servers.
- **Revocable.** Revoke any connection from **Settings, MCP connections**; revocation and a password reset both cut off existing tokens immediately.
- **Rate-limited and audited.** Requests are rate-limited per token and per account, and every tool call is written to your [audit log](/docs/programmatic-api#audit).

## Endpoint

The server speaks MCP over streamable HTTP at `https://app.glassmkr.com/mcp`. Point a compatible client at that URL and complete the browser authorization; there is nothing to install on your servers beyond the [Crucible agent](/docs/getting-started) you already run.

MCP is available on every plan; access is bounded by the same node quota and per-action rate limits as the [programmatic API](/docs/programmatic-api).

## Troubleshooting

If a connection does not complete, let your client run the OAuth flow end to end: a compatible client discovers the endpoints from the metadata documents and handles the browser sign-in itself, so you should not hand-configure endpoints or build the flow yourself. After you approve, the connection appears under **Settings, MCP connections** in the dashboard. To reset a client that is stuck on authorization, revoke it there and authorize again.