MCP Server — Connect AI Assistants and Agents to Glassy¶

Glassy includes a built-in Model Context Protocol (MCP) server that exposes 10 tools and lets AI assistants and agents — including Claude, Cursor, Windsurf, OpenCode, Hermes, Openclaw, Pi, and any other MCP-compatible client — search and interact with your knowledge base directly.

Updated July 9, 2026 (v2.35.0-beta.7): The server is now built on the official @modelcontextprotocol/sdk v2. A new glassy_obsidian_proxy tool, 3 prompts, 3 dynamic resources, completable() argument hints, and tier-based rate limiting (free 120/hr, Pro 1,200/hr) are now live. The Companion extension (v2.13.0) exposes a copy-pasteable config snippet in Settings → Integrations with the live server URL.

What is MCP?¶

The Model Context Protocol is an open standard that lets AI applications connect to external data sources. Instead of copying text into a chat window, your AI tool can search your actual knowledge base — bookmarks, notes, vault files — and get real results with citations. The Glassy implementation uses the official @modelcontextprotocol/sdk v2 with McpServer + NodeStreamableHTTPServerTransport (stateless) + createMcpExpressApp (DNS rebinding protection).

Setup¶

1. Enable the Feature Flag¶

In your .env file:

ENABLE_MCP_SERVER=true

Restart Glassy after changing flags.

2. Generate an MCP Key¶

Open Glassy and go to Settings → Integrations.
Find the MCP Connection section.
Click Generate MCP Key.
Copy the key immediately — it is shown only once and cannot be retrieved later.

The key looks like: gky_mcp_1a2b3c4d5e6f...

3. Configure Your AI Tool¶

The same Glassy MCP snippet works in any MCP-compatible client. Add it to your tool's MCP settings and restart.

Claude Desktop¶

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "glassy": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer gky_mcp_YOUR_KEY_HERE"
      }
    }
  }
}

Config file locations: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor¶

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "glassy": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer gky_mcp_YOUR_KEY_HERE"
      }
    }
  }
}

Other MCP-compatible clients¶

Windsurf, OpenCode, Hermes, Openclaw, Pi, and any other MCP client that supports HTTP transport can use the same configuration. Replace the URL and bearer token as needed for your tool's config format.

Remote Glassy instances

If Glassy is hosted on a remote server, replace http://localhost:3000 with your server's URL (e.g., https://app.glassy.fyi). Ensure the MCP endpoint is accessible — you may need to configure your reverse proxy or firewall.

4. Verify the Connection¶

Once configured, restart your AI tool. You should see Glassy's tools available. Try asking:

"Search my Glassy knowledge base for notes about deployment"

Your AI assistant or agent will call glassy_search and return results from your actual bookmarks, notes, and vault files.

Available Tools¶

Tool	What It Does
`glassy_search`	Search across bookmarks, notes, documents, vault files, and voice transcripts using hybrid text + semantic search
`glassy_add_capture`	Save a URL as a bookmark with optional title, note, and tags
`glassy_get_recent`	Fetch your most recent bookmarks and notes
`glassy_obsidian_query`	Search your Obsidian vault files specifically
`glassy_note_create`	Create a new note (text, checklist, or rich format)
`glassy_note_update`	Update an existing note's title, body, tags, or metadata
`glassy_note_delete`	Delete an existing note
`glassy_bookmark_update`	Update an existing bookmark's title, note, tags, or collection
`glassy_bookmark_delete`	Delete an existing bookmark
`glassy_obsidian_proxy`	Transparent proxy to your Obsidian Local REST API's `/mcp/` endpoint

Managing Your Key¶

Regenerate — click "Regenerate Key" in Settings to create a new key (old key is revoked immediately).
Revoke — click "Revoke Key" to permanently disable MCP access. Any AI tools using the key will lose access.
Key status — the MCP Connection section shows whether a key is active and when it was last used.

Security¶

MCP keys use the gky_mcp_ prefix and are encrypted at rest in the database.
Each key use mints a short-lived JWT (5 minutes) for session tracking.
Keys can be revoked instantly from Settings.
The MCP endpoint requires Bearer token authentication — unauthenticated requests receive 401.

Troubleshooting¶

Problem	Solution
"Invalid MCP API key format"	Ensure your key starts with `gky_mcp_` and is copied exactly
"Invalid MCP API key"	The key may have been revoked. Generate a new one in Settings
"Account deactivated"	Your account may have been inactivity-deleted. Contact support
Tool returns empty results	Ensure `ENABLE_CORPUS_INDEXER` and `ENABLE_KB_QUERY` are enabled and a backfill has been run
Connection refused	Verify Glassy is running and the URL in your config is correct

Obsidian MCP Proxy¶

If you use Obsidian with the Local REST API plugin, Glassy can proxy Obsidian's MCP endpoint through its own /mcp gateway. This gives your AI tools a single MCP connection that covers both Glassy and Obsidian content.

Enable with:

ENABLE_OBSIDIAN_MCP_PROXY=true

Configure your Obsidian connection in Settings → Obsidian first, then enable the proxy flag. All requests to /mcp/* are forwarded to your Obsidian instance with SSRF protection.