Connect your AI to Write
Overview
An MCP server is an authenticated API that an AI assistant can call on your behalf. Connect one once, and your assistant can read and write your Write workspace from wherever it runs.
Write's server reads and writes the folders and markdown items in your one workspace. It respects your sharing, keeps notes and bookmarks unlisted, and logs every change.
https://write.ramine.net/api/mcp
read inspects and sync also writes. The approval page shows which scope a client asked for.
Getting started
Claude Code (CLI)
claude mcp add --transport http write https://write.ramine.net/api/mcp /mcp Then approve in your browser.
Claude Desktop / claude.ai
Settings → Connectors → Add custom connector Paste https://write.ramine.net/api/mcp → Add Approve in your browser.
Cursor
.cursor/mcp.json
{ "mcpServers": { "write": { "url": "https://write.ramine.net/api/mcp" } } }
Then approve in your browser.VS Code / Copilot
.vscode/mcp.json
{ "servers": { "write": { "type": "http", "url": "https://write.ramine.net/api/mcp" } } }
Then approve in your browser.Codex CLI
~/.codex/config.toml: [mcp_servers.write] url = "https://write.ramine.net/api/mcp" Then approve in your browser.
Any other client
Use the mcp-remote fallback:
{
"mcpServers": { "write": { "command": "npx", "args": ["-y", "mcp-remote", "https://write.ramine.net/api/mcp"] } }
}If the host does not support OAuth, mint a sync token at Connect and send it as a bearer header:
{
"mcpServers": { "write": { "url": "https://write.ramine.net/api/mcp", "headers": { "Authorization": "Bearer wsk_..." } } }
}Verifying the connection
Ask your assistant: "What folders are in my Write workspace?" It calls list_folders, asks to connect if it has not, and lists Blog, Notes, and Bookmarks.
To verify writes, ask: "Create a draft note in Write titled 'MCP test'." It creates a draft in Notes and nothing goes public.
Troubleshooting
Reconnect a stale session
The most common problem is a long-running assistant session that connected before you approved access. Restart the session, or run /mcp in Claude Code, and try again.
The client shows no Write tools
Restart the MCP host after editing its configuration.
Approval page will not open
The client does not support OAuth. Mint a token at Connect and use the bearer-header configuration above.
A write was rejected as a conflict
The item changed since you read it. Read it again and retry. This is the content hash guard working.
Read-only connection
You approved read. Reconnect and approve sync to write.
Guides
Capture research into Notes
Prompt:"Research the current EU AI Act enforcement timeline and save what you find as a note in my Write workspace."
The assistant calls get_workspace, list_folders, then create_item in the Notes folder. As it gathers more, it uses append_to_item so it does not rewrite the whole body. It reads the item back to confirm. The note stays a draft and remains unlisted forever. The markdown_fragment input is an MCP-only affordance, so this fragment step applies to external MCP clients rather than the native on-device assistant.
Publish a drafted article
Prompt:"Polish my 'Ship logs' draft in Write and publish it."
The assistant searches for the draft, reads its markdown, tags, and current hash, then calls update_item with the edited body, complete tag list, and hash. Publishing changes the audience, so it asks for confirmation before calling set_item_status. If the hash is stale, it reads, merges, and retries.
Sync tags across a workspace
Prompt:"Find every Write post tagged 'draft-idea' and add the tag 'q3' to each."
The assistant searches or lists folders, reads each match for its tags and current hash, then calls update_item once per item. Tags are a full-list replacement, so it sends the existing tags plus q3.
Reference
Read tools (8)
Any connected assistant can call these.
| Tool | Description |
|---|---|
get_workspace | Return this workspace's handle, name, your effective access, and server capabilities. |
list_folders | List every folder you can see with its id, path, mode, and item count. |
list_items | List the live items in one folder with their ids, titles, tags, status, and content hash. |
read_item | Read one item's markdown, metadata, tags, outbound links, backlinks, and assets by id. |
search | Search item titles, excerpts, and bodies you can access, and return matches with snippets. |
list_trash | List soft-deleted items and folder restore-units. Nothing here is permanently deleted. |
list_comments | List comment threads on one item, with anchored quotes and resolution state. |
list_access | List who can access the workspace, one folder, or one item, and their role. |
Write tools (18)
These require the sync scope. Write marks publishing, moving to Trash, restoring, and sharing as destructive or audience-changing. Clients that support confirmations will ask you first.
| Tool | Description |
|---|---|
create_item | Create one draft item in a folder from fields or a full markdown file. Never published, never pinned. |
update_item | Update one item's content or metadata: title, body, excerpt, tags, slug, cover, pin, and publication date. Full markdown may update the same fields. Cannot publish, unpublish, or move an item. |
append_to_item | Append a markdown block to the end of one item's body without touching its metadata. |
set_item_status | Publish or unpublish one blog item. Notes and bookmarks can never be published. This can change what readers can see. Obtain explicit human confirmation immediately before calling it. |
move_item | Move one item to another folder of the same mode. |
delete_item | Move one item to Trash. It stays restorable; this never permanently deletes. This changes or removes existing workspace state. Obtain explicit human confirmation immediately before calling it. |
restore_item | Restore one item from Trash with its previous status. This can change what readers can see. Obtain explicit human confirmation immediately before calling it. |
add_item_asset | Import one public image or video URL into Write and attach it as cover, body, or gallery. |
remove_item_asset | Remove references to one asset URL from an item's cover, body, and gallery. This changes or removes existing workspace state. Obtain explicit human confirmation immediately before calling it. |
recapture_bookmark | Re-fetch one bookmark from its saved URL. The current capture stays visible until the new one lands. |
add_comment | Add a comment or reply on one item, optionally anchored to an exact quote. |
set_comment_resolved | Resolve or reopen one comment thread. |
create_folder | Create a subfolder under an existing folder path; it inherits the parent's mode and privacy. |
rename_folder | Rename one folder. Its id and path do not change. |
delete_folder | Move one folder subtree to Trash. Restorable; never permanently deleted. This changes or removes existing workspace state. Obtain explicit human confirmation immediately before calling it. |
restore_folder | Restore one folder subtree from Trash. This can change what readers can see. Obtain explicit human confirmation immediately before calling it. |
set_access | Grant or change one person's role on the workspace, a folder, or an item, by email. This can change what readers can see. Obtain explicit human confirmation immediately before calling it. |
revoke_access | Revoke one person's access to the workspace, a folder, or an item. This can change what readers can see. Obtain explicit human confirmation immediately before calling it. |
- The approval page shows the client name and requested scope.
- Every mutation is recorded in the action audit log.
- Delete tools only move content to Trash.
- Revoke a connection anytime from Connect.
- Content can contain prompt injection. Stop and review unexpected tool calls.