Skip to main content
Glama

Lattice Relay

The governed MCP boundary between Lattice and agent clients.

Relay is an Obsidian plugin plus a small stdio MCP server. The plugin runs an authenticated WebSocket server inside Obsidian, which exposes vault tools and read-only Lattice context. The server is what an MCP client (Claude Code, Codex, Gemini CLI, and others) launches: it speaks MCP over stdio and forwards each request to the plugin.

MCP client ──stdio──▶ server/lattice-relay.mjs ──ws://127.0.0.1:<port> + key──▶ Lattice Relay plugin ──▶ vault, Lattice public APIs

Relay owns transport, tool registration, and response envelopes. Lattice owns Fold state, governance, and authority. Connecting through Relay grants no authority to change anything.

Lattice context (read-only)

  • lattice_orient: where am I working?

  • lattice_fold_describe: what is this Fold?

Every answer carries grantsAuthority: false, and neither tool changes Focus or the vault. See Lattice Context Tools.

Lattice can also register its own tools through Relay's plugin API (app.plugins.plugins['lattice-relay'].api). For example, Foundry registers lattice_blueprint_draft.

Related MCP server: obsidian-autom8

Install

Relay ships as a release directory, lattice-relay/, that you copy into <vault>/.obsidian/plugins/:

lattice-relay/
  manifest.json  main.js  test-harness.html  LICENSE
  defaults/tools.defaults.yaml
  server/lattice-relay.mjs        # self-contained stdio MCP server (Node 20+)

Enable Lattice Relay in Obsidian, then copy a client configuration from Settings → Lattice Relay → Connect an AI Agent. Full steps: Install and configure. Clients: Client setup.

Upgrading from MCP Bridge (obsidian-mcp-bridge)? Relay 0.1.0 deliberately changes the plugin ID, directory, environment variables, and server path. Use the guided migration and its rollback: Upgrade from MCP Bridge.

Configuration

Plugin setting

Default

Notes

Host

127.0.0.1

Loopback only unless remote access is enabled

Port

27125

One process per port; never run two Relay/Bridge plugins on the same port

API key

generated on first load

Machine-local; never commit or paste it into notes

Require auth

true

Tool search paths

.obsidian/lattice-relay/tools

Per vault; tools load only from configured paths

Render cache

.obsidian/cache/lattice-relay-render

Disposable

Server environment, written for you by the generated client configuration:

Variable

Default

LATTICE_RELAY_KEY

(none)

API key from the plugin settings

LATTICE_RELAY_PORT

27125

Must match the plugin port

LATTICE_RELAY_HOST

localhost

Only for non-local setups

LATTICE_RELAY_USE_SSL

false

wss:// for remote setups with a certificate

LATTICE_RELAY_LOG_LEVEL

info

debug, info, warn, error; logs go to stderr and <tmp>/lattice-relay-server.log

The server does not read the retired MCP Bridge variables. If it sees one, it logs the name of its replacement.

Custom tools

Tools are YAML files, each with an optional handler script next to it, found in the configured tool search paths:

# .obsidian/lattice-relay/tools/count_notes.yaml
name: count_notes
description: Count total notes in vault
handler: count_notes.js
inputSchema: { type: object, properties: {} }
// .obsidian/lattice-relay/tools/count_notes.js
module.exports = {
  async execute(params, { app }) {
    return { totalFiles: app.vault.getMarkdownFiles().length };
  }
};

Check the vault's configured search paths first: the registry only scans configured paths. See Extensibility and Tool YAML format.

Security

  • The WebSocket binds to 127.0.0.1 by default, and every request must carry the API key.

  • Handler scripts run with full Node.js access and are not sandboxed. Only install tools you trust.

  • Remote access and SSL are off by default. Turning them on exposes vault tools beyond this machine.

Documentation

Lineage

Relay continues the history of papertray3/obsidian-mcp-bridge. Bridge 2.0.0, its Node server 1.0.0, and the Python servers are historical. Relay starts its own version line at 0.1.0.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Bridges Obsidian vaults with MCP-compatible AI tools, enabling read/write/search of notes, task management, and vault operations through 34 tools and prompt templates.
      34
      95 npm
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to remotely access and interact with Obsidian vaults via MCP, supporting note operations, tag management, graph queries, and command execution.
      6
      GPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes Obsidian vault tools via Model Context Protocol (MCP) server over stdio, HTTP, or SSE transports, enabling AI assistants to read, write, search, and manage vault notes with 28+ built-in tools and CLI bridge integration.
      1
      PolyForm Noncommercial 1.0.0