Obsidian MCP (pgvector + Ollama, self-hosted)

Request upload link

request_upload

Destructive

Generate a short-lived, single-use upload link tied to one vault path so a person can place a file when you don't have its bytes.

Instructions

Get a short-lived link a person can use to put a file into the vault. Requires write permission — a readwrite API key, or an OAuth token carrying the readwrite scope. Peer to write_file, which takes the bytes directly — use this one when you do not have them.

No MCP client can hand a tool the bytes of a file the user is looking at, and your shell cannot reach their machine. This mints a link bound to exactly one destination path: hand it to the person you are helping, they open it and pick a file, and it lands at path. Nothing else can be written with it.

The token lives in the URL's # fragment, which browsers never send to a server, so it stays out of access logs. Treat the whole URL as a secret — whoever holds it can write that one path, once, until it expires. Never put it in a query string: that would log it.

Single use, and no-clobber unless you ask otherwise. With overwrite=True the link also remembers what the file looked like now and refuses to publish if it changed in the meantime, so a stale link cannot silently undo an edit someone made while it was waiting.

From a shell you can upload without the page: curl -H "Authorization: Bearer <token>" -T <file> <base>/transfer/upload.

Then call check_upload(upload_id) to confirm the bytes landed and get their sha256. See get_vault_guide for how files fit into the vault.

Args: path: Vault-relative destination (e.g. "Attachments/photo.png"). overwrite: If True, allow replacing an existing file at path. expires_in: Seconds until the link dies. Clamped to 60–3600; defaults to TRANSFER_TOKEN_TTL_SECONDS (600). A link can never outlive the credential you are calling with, so the deadline in the result may be earlier than you asked for — it says so when that happens.

Input Schema

Name	Required	Description	Default
`path`	Yes
`overwrite`	No
`expires_in`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.8.2Sep 24, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
Addedv0.7.0Aug 19, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already flag a mutation with destructiveHint=true; the description goes well beyond by disclosing single-use semantics, no-clobber-by-default, the stale-link guard under `overwrite=True`, expiry clamping (60–3600) and credential-bound lifetime, plus the secret-handling rule for the URL fragment and the explicit warning never to put it in a query string. That is genuinely new operational context, not a restatement of the hints.

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

Conciseness4/5

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

Well front-loaded: purpose, then auth, then the alternative, then mechanics. Some material is arguably surplus for a tool call decision — the paragraph explaining why MCP clients can't pass bytes, and the raw curl recipe — though both are defensible for a model reasoning about capabilities. Slightly long, but each section is doing work.

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?

With an output schema present, return values needn't be enumerated, yet the description still flags that the result carries a deadline that may be earlier than requested and names the verifying follow-up call. For a single-use transfer-link mint with three params, an agent has everything needed to call it and act on the result.

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

Parameters5/5

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

Schema coverage is 0%, so the description must carry all parameter meaning — and it does: `path` gets a concrete format example ("Attachments/photo.png"), `overwrite` gets its replacement semantics and stale-check behavior, and `expires_in` gets units, clamp range, default source, and the caveat that the effective deadline may be earlier. Nothing material is left undocumented.

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?

First sentence gives a specific verb+resource+scope: a short-lived link that lets a person put a file into the vault. It then explicitly contrasts with the sibling `write_file` ("takes the bytes directly — use this one when you do not have them"), so the agent can route between the two without opening either schema.

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?

States the exact condition that selects this tool over its alternative (you don't have the bytes), states the follow-up step (`check_upload(upload_id)`), and points to `get_vault_guide` for vault conventions. The precondition (readwrite API key or OAuth scope) is spelled out, which is exactly the when-can-I-use-this information an agent needs.

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