markdown-vault-mcp

Fetch to Vault

fetch

Idempotent

Download a file from a URL directly into the vault, bypassing LLM context limits for large content. Saves markdown notes or binary attachments via server-side transfer.

Instructions

Download a file from a URL and save it to the vault.

Fetches content from an HTTP/HTTPS URL and writes it as a note or attachment. Designed for MCP-to-MCP file transfer when content is too large to pass through the LLM context window.

Context cost: zero for the bytes themselves — the file is downloaded server-side and saved to the vault. After a successful fetch, reference the file by its path (call read(path) only for small results, otherwise pass the path to other tools).

For .md paths: the response is decoded as UTF-8 text and saved as a markdown note with optional frontmatter. The index refresh is queued.

For other paths: the response is saved as a binary attachment. The existing attachment size limit applies.

Input Schema

TableJSON Schema

Name	Required	Description
`url`	Yes	Source URL to download from. Only http:// and https:// schemes are allowed. SSRF protection (via pvl-core's hardened ``fetch_url``, #862): the host is resolved and rejected unless every address is publicly routable (private, loopback, link-local, CGNAT/shared, and reserved ranges are all blocked), the validated IP is pinned for the connection (closing DNS rebinding), and ambient HTTP(S)_PROXY / .netrc settings are ignored. Redirects ARE followed (changed in #1116; through v3.1.0 a redirect was refused), and every hop repeats the whole chain above — a ``Location`` pointing at an internal target is refused exactly as a directly supplied one is. Because of that, the bytes need not come from the host in url: check the returned ``final_url`` when the source host matters.
`path`	Yes	Destination path in the vault (e.g. "notes/report.md" or "assets/diagram.png"). Extension determines handling: .md for notes, anything else for attachments.
`if_match`	No	Etag from 'read'; required by default to replace an existing file. A stale etag refuses the write. Omit for new files.
`timeout_s`	No	Download timeout in seconds (default 30). Increase for large files on slow connections.
`frontmatter`	No	Optional YAML frontmatter dict for .md files, e.g. {"title": "Report", "source": "http://..."}. Ignored for attachments.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv5.0.0Sep 15, 2026

changedInput schema / properties / if_match / description

Previous value: -"Optional etag from a previous 'read' call for\noptimistic concurrency. Omit to write unconditionally."New value: +"Etag from 'read'; required by default to replace an\nexisting file. A stale etag refuses the write. Omit for new files."

Addedv4.0.0Aug 26, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes far beyond the annotations by disclosing zero context cost, server-side downloading, UTF-8 decoding for .md, binary saving for others, queued index refresh, SSRF protections, redirect-following behavior, and the need to check final_url. This is rich behavioral context that the annotations alone do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured and front-loaded: the core purpose appears first, then the key context-cost insight, then path-dependent behavior. Every sentence carries useful information, including security caveats, and the formatting makes the .md vs attachment cases easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters, an output schema, and nontrivial security behavior, this description is complete: it covers schemes, SSRF, redirects, etag concurrency, timeouts, optional frontmatter, and post-fetch usage. An agent has everything needed to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter already has a detailed description, so the baseline is 3. The prose description adds context around path extension handling and frontmatter behavior, but most parameter meaning is already fully documented in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Download a file from a URL and save it to the vault') and clearly distinguishes the tool's niche: MCP-to-MCP transfer of content too large for the LLM context window. It also differentiates .md note behavior from attachment behavior, so an agent can tell this apart from read/write/vault_read siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly gives the intended use case ('MCP-to-MCP file transfer when content is too large to pass through the LLM context window') and tells the agent what to do afterward: reference the file by path, and call read(path) only for small results. This gives clear when-to-use guidance relative to sibling read and write tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.