Your first call
Once the server is registered with your client, every MCP tool surfaces directly in the model. The simplest read is a one-shot.
// In Claude Code or Claude Desktop, just ask:> "List the top 10 files in /team/finance"// The agent emits:→ drive_list_files({ path: "/team/finance", limit: 10 })// Server responds with a typed file list.← { files: [ ... ], truncated: false }
You do not need to mention the tool by name. The model picks it from the schema description. Tool names exist for the model and for logs — humans never type them directly.
The confirm flag
Every write tool requires confirm:true. The first call without it returns CONFIRM_REQUIRED with a one-line summary of what would change. The agent restates intent, then retries.
→ drive_delete_file({ path: "/team/finance/old-budget.pdf" })← { error: "CONFIRM_REQUIRED", summary: "Move /team/finance/old-budget.pdf to Trash (recoverable for 30 days)" }→ drive_delete_file({ path: "/team/finance/old-budget.pdf", confirm: true })← { deleted: true, recoverableUntil: "2025-05-30T00:00:00Z" }
Patterns that work
- 01Search-then-act: drive_search_files → drive_get_file → drive_label_file. Resolve before you mutate.
- 02Open once, batch-write: spreadsheet_open → spreadsheet_batch_update. Do not write cells one by one — slow and expensive on style retention.
- 03Time-bounded reads: always pass a range to calendar_list_events. Without one the agent gets a multi-year haystack.
- 04Move before delete: mailplus_move to a /Triage folder is reversible; mailplus_delete (when added) is not.
Anti-patterns
- 01Looping single-cell writes. Use spreadsheet_batch_update — atomic, faster, and preserves cell styles.
- 02Polling for changes. The MCP server does not stream. Subscribe at the agent level on a cadence you control.
- 03Storing fileIds across sessions. They are stable per-NAS but should be re-resolved if your auth user changes.
- 04Skipping the path-guard. Setting DRIVE_ROOT_PATH=/ is technically allowed and immediately wrong. Set the smallest prefix that covers your use case.
Session model
The MCP server holds the Synology session id internally. The agent never sees it, never manages refresh, never handles the auth dance.
Sessions auto-refresh on AUTH_EXPIRED. The retry is transparent to the tool call. If the underlying credential becomes invalid (password rotation), every tool call surfaces SYNOLOGY_API_ERROR with inner_code: 400.