evc-team-relay-mcp

**Give your AI agent read/write access to your Obsidian vault.**
> Your agent reads your notes, creates new ones, and stays in sync — all through the Team Relay API.
Works with **Claude Code**, **Codex CLI**, **OpenCode**, and any MCP-compatible client.
---
Quick Start
1. Install
**Option A — from PyPI (recommended):**
No installation needed — uvx downloads and runs automatically. Skip to step 2.
**Option B — from source:**
2. Configure your AI tool
Add the MCP server to your tool's config. Choose one authentication method:
**Agent key** (recommended) — create a key in the Obsidian plugin → Team Relay settings → **Agent Keys**. Supports read and write: list_files, read_file, tr_search, and upsert_file all work with a single key. Quickstart →
**Email + password** — use a dedicated agent account on your Relay instance.
Claude Code — agent key
Add to .mcp.json in your project root or ~/.claude/.mcp.json:
Claude Code — email/password
Codex CLI
Add to your codex.json:
OpenCode
Add to opencode.json:
From source (all tools)
If you installed from source instead of PyPI, replace "command": "uvx" / "args": ["evc-team-relay-mcp"] with:
**Environment variables:**
| Variable | Required | Description |
|----------|----------|-------------|
| RELAY_CP_URL | Yes | Control plane base URL |
| RELAY_AGENT_KEY | One of | Agent key from plugin settings — read + write (recommended) |
| RELAY_EMAIL | One of | Account email (email/password mode) |
| RELAY_PASSWORD | One of | Account password (email/password mode) |
Ready-to-copy config templates are also in config/.
3. Use it
Your AI agent now has these tools:
| Tool | Description |
|------|-------------|
| authenticate | Authenticate with credentials (auto-managed) |
| list_shares | List accessible shares (filter by kind, ownership) |
| list_files | List files in a folder share |
| **read_file** | Read a file by path from a folder share |
| read_document | Not implemented — no backend route in any auth mode, always raises |
| **upsert_file** | Create or update a file by path — **agent-key mode only**; raises in email/password (JWT) mode |
| write_document | Not implemented — no backend route in any auth mode, always raises |
| delete_file | Not implemented — no backend route in any auth mode, always raises |
**Typical workflow:** list_shares -> list_files -> read_file / upsert_file
Authentication is automatic — the server logs in and refreshes tokens internally.
Tool availability matrix
Not every tool works in every auth mode, and one group doesn't work in
*either* mode — these are two unrelated facts, so don't conflate them:
| Group | Tools | Status |
|-------|-------|--------|
| **Agent key**, folder shares | list_files, read_file, upsert_file | Working — **the only write path** in this MCP server |
| **JWT** (email/password) | list_files, tr_search, read_file | Working, **read-only** by design |
| **No backend route in either mode** | read_document, write_document, delete_file | Always raise ValueError — not an auth restriction |
- **Write access is agent-key-only, by sanctioned policy** (see
TR-05 (#0cdd5328)):
upsert_file is the only write tool with a working backend route, and it
only writes when an agent key (RELAY_AGENT_KEY / RELAY_AGENT_KEYS) is
configured. JWT mode calling upsert_file raises a clear ValueError
naming agent-key mode as the fix, instead of a confusing 404.