Connect over MCP

Glassray runs a customer-facing Model Context Protocol 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 below.

Endpoint

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:

OAuth (browser sign-in)

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.

API key

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

Claude Code
Cursor
Claude Desktop
claude.ai Connectors

OAuth (a browser sign-in pops on first use):

claude mcp add --transport http glassray https://app.glassray.ai/api/public/mcp

Or with an API key:

claude mcp add --transport http glassray https://app.glassray.ai/api/public/mcp \
  --header "Authorization: Bearer <your-api-key>"

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "glassray": {
      "url": "https://app.glassray.ai/api/public/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "glassray": {
      "url": "https://app.glassray.ai/api/public/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

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:

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

Docs-search endpoint

https://glassray.ai/docs/mcp - no authentication.

Add it to Claude Code:

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.

Get started

Glassray CLI

Coach (local)

Concepts

Trace sources

Glassray SDK

Integrations

Explore

Endpoint

Authentication

OAuth (browser sign-in)

API key

Mint an API key

Connect your client

Tools

Read (require `mcp:read`)

Ask (require `mcp:read`)

Trigger (require `mcp:write`)

Search these docs over MCP

Docs-search endpoint

​Endpoint

​Authentication

OAuth (browser sign-in)

API key

​Mint an API key

​Connect your client

​Tools

​Read (require mcp:read)

​Ask (require mcp:read)

​Trigger (require mcp:write)

​Search these docs over MCP

Docs-search endpoint

Endpoint

Authentication

Mint an API key

Connect your client

Tools

Read (require `mcp:read`)

Ask (require `mcp:read`)

Trigger (require `mcp:write`)

Search these docs over MCP