Second Brain — AI Knowledge Layer¶

Glassy Second Brain turns your bookmarks, notes, documents, voice transcripts, and Obsidian vault files into a searchable knowledge base that AI agents can query directly. It bridges the gap between your personal knowledge and the AI assistants and agents you use every day.

Updated July 9, 2026 (v2.35.0): The MCP server is now built on the official @modelcontextprotocol/sdk v2. The hand-rolled JSON-RPC endpoint has been removed. The server now exposes 10 tools, including glassy_obsidian_proxy, plus 3 MCP prompts and 3 dynamic resources. Tier-based rate limiting (free 120/hr, Pro 1,200/hr) is wired. The Companion extension (v2.13.0) shows MCP config snippets in Settings → Integrations with the live server URL.

What It Does¶

Indexes everything you save — bookmarks, notes, documents, voice transcripts, and vault files are automatically embedded and searchable.
Hybrid search — combines BM25 full-text search (keyword matching) with vector semantic search (meaning-based) for the best of both worlds.
MCP server (real SDK) — exposes your knowledge base to Claude, Cursor, Windsurf, OpenCode, Hermes, Openclaw, Pi, and any MCP-compatible AI tool via the official @modelcontextprotocol/sdk v2 (McpServer + NodeStreamableHTTPServerTransport + createMcpExpressApp DNS-rebinding protection).
Knowledge Base workspace — a dedicated search UI (#/kb) in the Glassy dashboard for browsing and discovering your indexed content.
Prompts and resources — three reusable prompt templates (glassy_summarize, glassy_capture_prompt, glassy_daily_brief) and three dynamic resources (glassy://kb/search/{query}, glassy://recent/{sourceType}, glassy://status) are also registered with the MCP server.

How It Works¶

flowchart LR
    A[Bookmarks] --> E[Corpus Indexer]
    B[Notes] --> E
    C[Documents] --> E
    D[Vault Files] --> E
    E --> F[content_embeddings]
    E --> G[FTS5 Index]
    F --> H[Semantic Search]
    G --> I[Text Search]
    H --> J[RRF Merge]
    I --> J
    J --> K[KB Query API]
    J --> L[MCP Server SDK]
    K --> M[Dashboard KB UI]
    L --> N[Claude / Cursor / Windsurf]
    L --> O[OpenCode / Hermes / Openclaw / Pi]
    L --> P[Companion MCP Bridge]
    P --> Q[window.location.origin + /mcp]

Content is embedded — when you save a bookmark, create a note, or sync a vault file, the corpus indexer generates a vector embedding and stores it in content_embeddings.
Text is indexed — content is also added to an FTS5 full-text index for BM25 keyword search.
Queries merge both — when you search, both semantic and text results are combined via Reciprocal Rank Fusion (RRF) for ranked, deduplicated results.
AI tools connect via the real MCP SDK — Claude, Cursor, Windsurf, OpenCode, Hermes, Openclaw, Pi, and other MCP clients connect to Glassy's /mcp endpoint and call tools like glassy_search to query your knowledge base. The Companion extension (v2.13.0) shows the live window.location.origin + '/mcp' config snippet in Settings → Integrations.

Available MCP Tools¶

Tool	Description
`glassy_search`	Hybrid semantic + text search across bookmarks, notes, documents, vault files, and voice transcripts
`glassy_add_capture`	Save a URL as a bookmark in your GlassyKeep library
`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) in your Glassy library
`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` (v2.33.0)	Transparent proxy to your Obsidian Local REST API's `/mcp/` endpoint. External AI clients see both Glassy-native and Obsidian-proxied tools through a single MCP surface. SSRF-protected, TLS fallback, Docker host override.

MCP Prompts¶

Prompt	Description
`glassy_summarize`	Content summarization template (input: URL or content)
`glassy_capture_prompt`	URL capture guidance template (input: URL, optional collection)
`glassy_daily_brief`	End-of-day review template (input: date)

MCP Resources¶

Resource	Description
`glassy://kb/search/{query}`	Search results as a structured resource
`glassy://recent/{sourceType}`	Recent items filtered by source type
`glassy://status`	Corpus health snapshot

`completable()` Argument Hints¶

The MCP server uses completable() to expose argument autocompletion to LLM clients. Fields with completable hints:

glassy_search.sources — enum (bookmark, note, document, vault_file, voice_transcript)
glassy_get_recent.source_type — enum (bookmark, note, vault_file)
glassy_note_create.type — enum (text, checklist, rich)
glassy_note_create.color — free string with palette hints

Tier-Based Rate Limiting (v2.33.0)¶

Second Brain has two separate rate limiters, each tier-gated by hasActivePaidAccess(req.user):

1. KB Query API (`/api/kb/query`)¶

Uses kbTierLimiter middleware in server/routes/kb.js:

Tier	Limit
Free	30 requests / hour
Pro	300 requests / hour

Keyed by client IP (express-rate-limit default). Multiple free users behind the same NAT will share the 30/hour limit.

2. MCP Tool Calls (`/mcp` `tools/call`)¶

Uses mcpTierLimiter in server/mcp/index.js. Only tools/call messages are counted — handshake, discovery, notifications, and ping are never throttled:

Tier	Limit
Free	120 tool calls / hour
Pro	1,200 tool calls / hour

Keyed per-user via mcpRateLimitKey (falls back to IP only when no user is resolved from the MCP key).

Feature Flags¶

Second Brain features are gated behind environment flags for controlled rollout. All default to false (disabled).

Flag	What It Gates
`ENABLE_CORPUS_INDEXER`	Embedding generation and storage
`ENABLE_KB_QUERY`	KB Query API endpoint (`/api/kb/query`)
`ENABLE_MCP_SERVER`	MCP server on `/mcp` + MCP key settings UI
`ENABLE_KB_UI`	Knowledge Base workspace (`#/kb` route)
`ENABLE_HYBRID_SEARCH`	BM25 + vector hybrid search (FTS5)
`ENABLE_MCP_BRIDGE`	Companion MCP token exchange
`ENABLE_OBSIDIAN_MCP_PROXY`	Obsidian MCP proxy through Glassy

Set them in your .env file:

ENABLE_CORPUS_INDEXER=true
ENABLE_KB_QUERY=true
ENABLE_MCP_SERVER=true
ENABLE_KB_UI=true
ENABLE_HYBRID_SEARCH=true

Getting Started¶

Enable the feature flags in your .env file.
Run the backfill — index your existing content:
```
POST /api/kb/backfill
```
Check progress at GET /api/kb/backfill-status.
Generate an MCP key — go to Settings → Integrations → MCP Connection and click "Generate MCP Key".
Configure your AI tool — copy the config snippet for Claude Desktop, Cursor, Windsurf, OpenCode, Hermes, Openclaw, Pi, or any MCP-compatible client from the settings panel.
Start searching — open the KB workspace at #/kb in your dashboard, or ask your AI tool to search your knowledge base.

Architecture Notes¶

MCP tools call services directly — no HTTP double-hop. Tools import and call corpusIndexer, aiContextBroker, and Database in-process.
JWT-bridging for auth — MCP API keys (gky_mcp_*) are validated, then a short-lived JWT (5 min) is minted for session tracking.
Dimension safety — every embedding query filters by dimensions = ? to prevent cosine similarity crashes on dimension mismatch.
Dual-write transition — during rollout, embeddings are written to both the new content_embeddings table and the legacy bookmark_embeddings table.