Obsidian MCP (pgvector + Ollama, self-hosted)

request_upload

Generate a secure, one-time upload link for a chosen path in Obsidian, letting a user upload a file without exposing full write access. Link expires and can block overwrites.

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

TableJSON Schema

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

Output Schema

TableJSON 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

A5/5.0

Behavior5/5

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

With no annotations, the description carries full weight and does so thoroughly. It discloses permission requirements (readwrite key/scope), single-use and no-clobber behavior, overwrite semantics with optimistic concurrency, expiry clamping, the secret-in-fragment security detail, and a direct curl example. It even warns against logging the URL, making all behavioral traits explicit.

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?

Although lengthy, every sentence earns its place: purpose, permission, alternative, security, behavior, parameter details, curl example, and follow-up references. The structure is front-loaded with the core purpose and then flows logically into usage, security, and parameters, with an Args block at the end. No filler words.

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 the tool's complexity (3 params, security implications, interaction with other tools), the description is complete. It covers return flow (check_upload with sha256), expected usage from both MCP and shell, and relevant siblings. An agent can correctly select and invoke this tool with no further documentation.

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 has 0% description coverage, so the description must fully document each parameter. It explains 'path' with an example, 'overwrite' with behavior, and 'expires_in' with clamping, defaults, and the caveat about credential lifetime. Every schema parameter is meaningfully expanded.

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?

The description opens with a precise verb and object: 'Get a short-lived link a person can use to put a file into the vault.' It immediately distinguishes itself from the sibling 'write_file' by stating it is the peer for when you don't have the bytes, so an agent can tell them apart without opening schemas.

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 tells when to use this tool vs alternatives: 'Peer to write_file, which takes the bytes directly — use this one when you do not have them.' It also refers to check_upload for confirming the upload and get_vault_guide for vault context, giving the agent a complete usage path.

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