The EVC Team Relay MCP Server gives AI agents secure read/write access to an Obsidian vault through the Team Relay API.
Authenticate — Log in to the Relay Control Plane via environment variables (RELAY_CP_URL, RELAY_EMAIL, RELAY_PASSWORD); tokens are managed and refreshed automatically
List Shares — Retrieve accessible shares with optional filtering by type (doc or folder) and ownership
List Files — Browse all files within a specific folder share, returning a map of paths to document IDs and types
Read File — Read a file from a folder share by path (recommended high-level method for folder shares)
Read Document — Low-level access to read content directly by doc_id, useful for doc shares or advanced use cases
Upsert File — Create or update a file in a folder share, with automatic detection of whether to create or update
Write Document — Low-level write to replace a document's full content by doc_id (intended for doc shares)
Delete File — Remove a file from a folder share; deletion syncs to Obsidian on the next sync cycle
Enhanced security — No shell execution, validated inputs, and automatic token management
Broad compatibility — Works with Claude Code, Codex CLI, OpenCode, and any MCP-compatible client; supports remote deployment via HTTP transport
Allows AI agents to read from and write to an Obsidian vault, enabling capabilities such as listing files, reading document content, and creating or updating notes with real-time synchronization via the Team Relay API.
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.
Option A — from PyPI (recommended):
No installation needed — uvx downloads and runs automatically. Skip to step 2.
Option B — from source:
git clone https://github.com/entire-vc/evc-team-relay-mcp.git
cd evc-team-relay-mcp
uv sync # or: pip install .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.
Add to .mcp.json in your project root or ~/.claude/.mcp.json:
{
"mcpServers": {
"evc-relay": {
"command": "uvx",
"args": ["evc-team-relay-mcp"],
"env": {
"RELAY_CP_URL": "https://cp.yourdomain.com",
"RELAY_AGENT_KEY": "tr_agent_your_key_here"
}
}
}
}{
"mcpServers": {
"evc-relay": {
"command": "uvx",
"args": ["evc-team-relay-mcp"],
"env": {
"RELAY_CP_URL": "https://cp.yourdomain.com",
"RELAY_EMAIL": "agent@yourdomain.com",
"RELAY_PASSWORD": "your-password"
}
}
}
}Add to your codex.json:
{
"mcp_servers": {
"evc-relay": {
"type": "stdio",
"command": "uvx",
"args": ["evc-team-relay-mcp"],
"env": {
"RELAY_CP_URL": "https://cp.yourdomain.com",
"RELAY_AGENT_KEY": "tr_agent_your_key_here"
}
}
}
}Add to opencode.json:
{
"mcpServers": {
"evc-relay": {
"command": "uvx",
"args": ["evc-team-relay-mcp"],
"env": {
"RELAY_CP_URL": "https://cp.yourdomain.com",
"RELAY_AGENT_KEY": "tr_agent_your_key_here"
}
}
}
}If you installed from source instead of PyPI, replace "command": "uvx" / "args": ["evc-team-relay-mcp"] with:
"command": "uv",
"args": ["run", "--directory", "/path/to/evc-team-relay-mcp", "relay_mcp.py"]Environment variables:
Variable | Required | Description |
| Yes | Control plane base URL |
| One of | Agent key from plugin settings — read + write (recommended) |
| One of | Account email (email/password mode) |
| One of | Account password (email/password mode) |
Ready-to-copy config templates are also in config/.
Your AI agent now has these tools:
Tool | Description |
| Authenticate with credentials (auto-managed) |
| List accessible shares (filter by kind, ownership) |
| List files in a folder share |
| Read a file by path from a folder share |
| Not implemented — no backend route in any auth mode, always raises |
| Create or update a file by path — agent-key mode only; raises in email/password (JWT) mode |
| Not implemented — no backend route in any auth mode, always raises |
| 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.
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 |
| Working — the only write path in this MCP server |
JWT (email/password) |
| Working, read-only by design |
No backend route in either mode |
| Always raise |
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.
read_document, write_document, and delete_file are a separate,
independent gap — the control plane has no backend route for them at
all, in agent-key mode either. Switching to an agent key will not
make them work: doc-share live content is CRDT/WebSocket-only (no REST
bridge), and per-file delete has no DELETE route server-side yet. If
routes for these are ever added, they'd still follow the agent-key-only
write policy above — JWT would stay read-only.
Related MCP server: Obsidian Knowledge Management MCP Server
For shared or server-side deployments, run as an HTTP server:
# Direct
uv run relay_mcp.py --transport http --port 8888
# Docker (pulls from Docker Hub automatically)
RELAY_CP_URL=https://cp.yourdomain.com \
RELAY_EMAIL=agent@yourdomain.com \
RELAY_PASSWORD=your-password \
docker compose up -d
# Or pull explicitly
docker pull deadalusevc/evc-team-relay-mcp:latestBy default the server binds to 127.0.0.1 (localhost-only) — the endpoint is not
reachable over the network even if the host has a public IP. This matches the common
case of a single MCP client on the same machine as the server.
Then configure your MCP client to connect via HTTP:
{
"mcpServers": {
"evc-relay": {
"type": "streamable-http",
"url": "http://127.0.0.1:8888/mcp"
}
}
}If your MCP client runs on a different machine than the server, tunnel to the localhost-bound port instead of exposing it publicly:
# From the client machine, forward local 8888 to the server's localhost:8888
ssh -N -L 8888:127.0.0.1:8888 user@your-serverThen point the client config at http://127.0.0.1:8888/mcp as above — traffic
goes through the SSH tunnel, and the server's bind address never needs to change.
If you genuinely need the server to accept connections from other hosts directly
(e.g. it sits behind a reverse proxy that terminates TLS and handles auth), pass
--host explicitly:
uv run relay_mcp.py --transport http --port 8888 --host 0.0.0.0Only do this behind a reverse proxy or firewall — the MCP HTTP endpoint itself
has no built-in authentication, so binding it to 0.0.0.0 on an open network
exposes every relay tool call to anyone who can reach the port.
The MCP server provides significant security advantages over shell-based integrations:
No shell execution — all operations are Python function calls via JSON-RPC, eliminating command injection risks
No CLI arguments — credentials and tokens are never passed as process arguments (invisible in ps output)
Automatic token management — the server handles login, JWT refresh, and token lifecycle internally; the agent never touches raw tokens
Typed inputs — all parameters are validated against JSON Schema before execution
Single persistent process — no per-call shell spawning, no environment leakage between invocations
Note: If you're using the OpenClaw skill (bash scripts), consider migrating to this MCP server for a more secure and maintainable integration.
┌─────────────┐ MCP ┌──────────────┐ REST API ┌──────────────┐ Yjs CRDT ┌──────────────┐
│ AI Agent │ ◄────────────► │ MCP Server │ ◄─────────────► │ Team Relay │ ◄──────────────► │ Obsidian │
│ (any tool) │ stdio / HTTP │ (this repo) │ read/write │ Server │ real-time │ Client │
└─────────────┘ └──────────────┘ └──────────────┘ sync └──────────────┘The MCP server wraps Team Relay's REST API into standard MCP tools. Team Relay stores documents as Yjs CRDTs and syncs them to Obsidian clients in real-time. Changes made by the agent appear in Obsidian instantly — and vice versa.
Python 3.10+ with uv (recommended) or pip
A running EVC Team Relay instance (self-hosted or hosted)
A user account on the Relay control plane
Product | What it does | Link |
Team Relay | Self-hosted collaboration server | |
Team Relay Plugin | Obsidian plugin for Team Relay | |
Relay MCP | MCP server for AI agents | this repo |
OpenClaw Skill | OpenClaw agent skill (bash) | |
Local Sync | Vault <-> AI dev tools sync | |
Spark MCP | MCP server for AI workflow catalog |
MIT
Authenticate with the Relay Control Plane.
Uses RELAY_EMAIL and RELAY_PASSWORD env vars. Returns a status message. The token is managed internally — subsequent tool calls use it automatically.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that authentication uses env vars, returns a status message, and that the token is managed automatically for subsequent calls. This covers key behavioral traits without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with purpose. Every sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an output schema (though not shown), the description sufficiently explains authentication flow, environment variable usage, and automatic token management. It is complete for a simple auth tool with no siblings in the same domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so baseline is 4. The description adds value by explaining that environment variables are used, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Authenticate with the Relay Control Plane', specifying the verb and resource. It is distinct from sibling tools that all perform file or document operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the use of environment variables (RELAY_EMAIL, RELAY_PASSWORD) and notes that the token is managed internally, implying it should be called first. No explicit exclusions or alternatives are needed given no sibling auth tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a file from a folder share.
Removes the file from the folder's metadata registry. The file disappears from Obsidian on next sync.
Args: share_id: UUID of the folder share. file_path: File path within the folder (e.g. "old-note.md").
Returns: JSON with path and status.
| Name | Required | Description | Default |
|---|---|---|---|
| share_id | Yes | ||
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly states the destructive nature ('Delete'), the effect on metadata registry, and the sync behavior with Obsidian. It also mentions the return format. However, it does not cover permanence or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a front-loaded summary. Every sentence provides value: one-line purpose, two behavioral lines, and a structured Args section. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, behavior, parameters, and return value. Given the simplicity of the tool (delete a file), it is nearly complete. Minor missing details like error handling do not detract significantly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully explains both parameters: share_id as UUID and file_path with an example. This adds significant meaning beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear verb and resource: 'Delete a file from a folder share.' It distinguishes from siblings like read_document and upsert_file by specifying deletion and metadata removal. Additional context about Obsidian sync further clarifies the tool's effect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to delete a file), but does not explicitly state when not to use or mention alternatives among siblings. No prerequisites or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files in a folder share.
Args: share_id: UUID of the folder share.
Returns: JSON with doc_id and files map (path -> {doc_id, type}).
| Name | Required | Description | Default |
|---|---|---|---|
| share_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It only mentions listing files, not whether it's read-only, requires auth, or any side effects. Incomplete for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: one-sentence purpose, Args/Returns format. Every sentence is informative with no redundancy. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (though not detailed), the description adequately covers return structure. Simple tool with one param, but missing error conditions or usage notes. Overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the sole parameter share_id by calling it a 'UUID of the folder share', which the schema (0% coverage) lacked. Effectively clarifies the parameter's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists files in a folder share, distinguishing it from siblings like list_shares (shares list) and read_file (single file). It specifies the argument and return structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives. The required parameter hint is implicit but not enough; lacks context like needing a share_id from list_shares.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read document content by doc_id (low-level).
For doc shares, omit doc_id — it defaults to share_id. For folder shares, pass the file's doc_id from list_files. Prefer read_file for folder shares.
Args: share_id: UUID of the share (for ACL check). doc_id: Document UUID. Defaults to share_id for doc shares. key: Yjs shared type key. Default "contents".
Returns: JSON with doc_id, content, format.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | contents | |
| doc_id | No | ||
| share_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavior like defaulting doc_id to share_id for doc shares, and returns JSON with specific fields. No annotations exist, so description carries burden. Could be more explicit about read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with a summary line, usage cases, and an Args section. It is informative but slightly long; could be more concise without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists and sibling tools are listed, the description covers all necessary context: parameters, defaults, and when to use alternatives. It is complete for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds substantial meaning beyond the input schema: explains share_id as UUID for ACL check, doc_id defaults, and key as Yjs shared type key. For 0% schema coverage, this fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads document content by doc_id and is low-level. It differentiates from sibling tools like read_file by specifying when to use each.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidelines: for doc shares omit doc_id, for folder shares pass doc_id from list_files, and prefers read_file for folder shares. Also clarifies defaults and arguments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a file from a folder share by its path.
Resolves path -> doc_id automatically. This is the recommended way to read files from folder shares.
Args: share_id: UUID of the folder share. file_path: File path within the folder (e.g. "Marketing/plan.md").
Returns: JSON with doc_id, content, format, path.
| Name | Required | Description | Default |
|---|---|---|---|
| share_id | Yes | ||
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool resolves path to doc_id automatically, which is a behavioral trait. However, with no annotations provided, it fails to mention whether the operation is read-only, any authorization requirements, error behavior, or side effects. The read operation is implied but not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a brief statement of purpose, a key behavioral note, and clear parameter and return explanations. Every sentence adds value, making it efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema (though not shown), the description covers the main functionality, return fields, and paths. It could mention edge cases like missing files or path formats, but overall it's sufficiently complete for a read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for parameters. The description compensates by explaining share_id as UUID and file_path with an example (e.g., 'Marketing/plan.md'). This adds significant meaning beyond the bare schema, though no validation details are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool reads a file from a folder share using a path. It specifies the resource ('folder share') and verb ('Read'), and differentiates from siblings like list_files and read_document by being the recommended method for reading files from folder shares.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'This is the recommended way to read files from folder shares,' implying it's preferred over alternatives, but it does not explicitly state when to avoid this tool or mention specific alternatives like read_document. More explicit guidance would be beneficial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a file in a folder share.
Automatically detects whether the file exists:
Existing file -> updates content (PUT)
New file -> creates file and registers in folder metadata (POST)
This is the recommended way to write files to folder shares.
Args: share_id: UUID of the folder share. file_path: File path within the folder (e.g. "notes/todo.md"). content: Full text content to write.
Returns: JSON with doc_id, path, length, operation ("created" or "updated").
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| share_id | Yes | ||
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the PUT/POST behavior and the returned operation field. It does not mention side effects, error conditions, or permission requirements, which is acceptable for a straightforward file write but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary line, a bullet list of arguments, and a return statement. It is concise and front-loaded. One could slightly tighten the bullet list, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description's brief return explanation suffices. All 3 required parameters are explained, and the behavior is clear. It is complete enough for a tool with moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides clear, semantic explanations for all three parameters (share_id as UUID, file_path as path, content as text) beyond the schema titles. Since schema coverage is 0%, the description fully compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create or update a file') and resource ('in a folder share'). It distinguishes itself from siblings like delete_file, read_file, and write_document by being the recommended write tool. The verb-resource combination is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the tool automatically detects file existence and uses PUT/POST accordingly. It marks itself as 'the recommended way to write files to folder shares,' providing clear context. However, it does not explicitly state when to use alternatives like write_document, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write content to a document by doc_id (doc shares only).
For folder shares, use upsert_file instead.
Args: share_id: UUID of the share (for ACL check). doc_id: Document UUID. content: Full text content to write (replaces entire document). key: Yjs shared type key. Default "contents".
Returns: JSON with doc_id, length.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | contents | |
| doc_id | Yes | ||
| content | Yes | ||
| share_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description reveals key behavior: 'replaces entire document', mentions ACL check via share_id. Could specify if document must exist, but sufficient for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences plus bullet-like arg list. No wasted words, well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core usage, parameter roles, and return format. Missing edge cases like non-existent doc, but adequate for a simple write tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage; description adds meaning for all parameters: share_id for ACL, doc_id as UUID, content as full text, key default. Also explains return fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Write content to a document' with specific resource (doc_id) and scope ('doc shares only'), distinguishing it from sibling upsert_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (doc shares) and when not ('For folder shares, use upsert_file instead'), providing a clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0authenticatedelete_filelist_fileslist_sharesread_documentread_fileupsert_filewrite_documentScored across 8 tools
Each tool has a clearly distinct purpose: authentication, managing shares, listing files, reading/writing via path or doc_id, and deleting files. No two tools overlap in functionality.
All tools follow a consistent verb_noun snake_case pattern (e.g., list_files, upsert_file, read_document). There are no deviations or mixed conventions.
With 8 tools, the set is well-scoped for managing files within shares. Each tool serves a specific operation, and the count is suitable for the domain without being excessive or insufficient.
The tool surface covers all core operations: authentication, listing shares and files, reading, writing (create/update), and deleting files. There are no obvious gaps for the intended purpose of managing files in folder and doc shares.
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Personal context for every AI: search, read, and write back to your private Markdown library of articles, threads, PDFs, notes, and captured ChatGPT/Claude/Gemini/Grok conversations. OAuth 2.1 paste-and-authorize or revocable tiered Agent keys (read_only / edit / full). Every agent edit is versioned and revertible.
