> ## Documentation Index
> Fetch the complete documentation index at: https://glassray.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect over MCP
> Connect Claude Code, Cursor, or Claude Desktop to your Glassray organization and work with your traces, flows, and deviations conversationally.
Glassray runs a customer-facing [Model Context Protocol](https://modelcontextprotocol.io) server so your coding agent can query **your organization's** traces, flows, specs, and deviations - and trigger scans - right from your editor. Ask things like *"what deviations did Glassray find this week?"*, *"show me the evidence for that one"*, or *"find traces where retrieval returned nothing."*
This is the **product** MCP server (your data, authenticated). Glassray's docs also expose a separate, unauthenticated **docs-search** MCP - see [Search these docs over MCP](#search-these-docs-over-mcp) below.
## Endpoint
```http theme={null}
POST https://app.glassray.ai/api/public/mcp
```
It speaks streamable HTTP - point any MCP client that supports the HTTP transport at it.
## Authentication
Two ways in, same tools:
For Claude, Cursor, and claude.ai Connectors. Add the server URL and a browser sign-in pops on first use - no key to copy. A signed-in org member gets read **and** trigger tools.
For CI and headless agents. Use an org key with **`mcp:read`** (gates the endpoint and every read tool); the trigger tools additionally require **`mcp:write`**.
### Mint an API key
In the dashboard, go to **Settings → API keys → MCP access** and click **Create MCP key** (admin-only). Glassray mints an org key with both `mcp:read` and `mcp:write`, shows it **once**, and gives you a ready-to-paste connect command. Manage or revoke it from the key list on the same page.
Auth failures map cleanly: `401` for a missing/invalid credential, `403` for a valid key without `mcp:read`, and `503` for a transient sign-in failure (retry - your key isn't revoked).
## Connect your client
OAuth (a browser sign-in pops on first use):
```bash theme={null}
claude mcp add --transport http glassray https://app.glassray.ai/api/public/mcp
```
Or with an API key:
```bash theme={null}
claude mcp add --transport http glassray https://app.glassray.ai/api/public/mcp \
--header "Authorization: Bearer "
```
Add to `.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"glassray": {
"url": "https://app.glassray.ai/api/public/mcp",
"headers": { "Authorization": "Bearer " }
}
}
}
```
Add to `claude_desktop_config.json`:
```json theme={null}
{
"mcpServers": {
"glassray": {
"url": "https://app.glassray.ai/api/public/mcp",
"headers": { "Authorization": "Bearer " }
}
}
}
```
If your client can't send custom HTTP headers directly, connect through an `mcp-remote`-style bridge, or use the OAuth flow instead.
In claude.ai, go to **Settings → Connectors → Add custom connector** and enter the server URL:
```text theme={null}
https://app.glassray.ai/api/public/mcp
```
Sign-in happens in the browser over OAuth.
## Tools
### Read (require `mcp:read`)
| Tool | What it does |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_flows` | The org's flows, newest first, with derived state and member counts. |
| `get_flow` | One flow in full: state, member count, code anchors, its code-derived rules (with rationale), good/bad examples, and linked deviations. |
| `list_flow_traces` | A flow's member traces and how each one joined (method, reason, confidence). |
| `list_traces` | Trace metadata, newest first; matches a Helix or external id. |
| `get_trace` | One trace plus a windowed excerpt of the raw provider document. |
| `list_specs` | Generated behavioral specs. |
| `get_spec` | One spec's metadata, its system-level intent (product context + system-wide rules), and the windowed markdown document (manual imports only - flow-driven orgs have no document). |
| `list_deviations` | Deviation types for a spec, pending-first, with instance counts. |
| `get_deviation` | One deviation type in full: recipe, instances and evidence, deep-search state, optional fix markdown. |
| `list_trace_sources` | Connected sources and their sync health. |
| `list_sync_jobs` | Sync-job history, filterable by source and status. |
| `get_run_status` | The lifecycle of a discovery or deep-search run. |
### Ask (require `mcp:read`)
| Tool | What it does |
| ---------------- | ------------------------------------------------------------------------------------ |
| `find_traces` | Natural-language search over your corpus → a curated set (or a clarifying question). |
| `analyze_traces` | Reason over a given set of trace ids → an analysis plus outliers. |
| `refine_traces` | Narrow or grow a working set per an instruction → the new set. |
These are the same primitives behind [Ask Glassray](/ask-glassray) - carry the working set by value (trace ids) from one call to the next.
### Trigger (require `mcp:write`)
| Tool | What it does |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `trigger_trace_sync` | Enqueue a manual/backfill sync for a pull source. |
| `run_deviation_discovery` | Start a discovery run over a sample of traces against the spec - metered work. |
| `run_deep_search` | Scan history for more recurrences of one deviation type - metered work. |
| `create_deviations` | Log one or more accepted deviations from the conversation, linking a reported trace. |
| `create_flow` | Declare a new flow by hand - a manual, active flow for one that discovery/clustering hasn't surfaced yet. |
| `connect_traces_to_flow` | Attach existing traces to a flow as manual members (e.g. to place a trace discovery missed, or correct a misclassification). |
| `update_deviation_status` | Accept or reject a deviation type or instance. Accepting a type fans out fix generation, a deep-search scan, and notification. |
Trigger tools return immediately with an id - poll a run with `get_run_status`. List results are paginated (up to 50 per page); large documents come back as character-windowed excerpts you page through.
## Search these docs over MCP
Separately from the product server above, these documentation pages expose an **unauthenticated** MCP server you can point an AI tool at to search the Glassray docs. It only reads this documentation - never your data.
`https://glassray.ai/docs/mcp` - no authentication.
Add it to Claude Code:
```bash theme={null}
claude mcp add --transport http glassray-docs https://glassray.ai/docs/mcp
```
Any MCP client that supports the HTTP transport works - point it at the same URL.