Share MCP Server
Control who can access a document, asset, or folder — list, grant, and revoke per-user roles without touching anyone else.
|
|
https://api.charmiq.ai/mcp/shareShare Roles
owner | |
editor | |
commenter | |
viewer |
manager (between editor and owner): a manager can change a folder's sharing without being an owner. The Share server reads manager back on folders but does not grant it; use owner for full control.Tools
list_shares | |
share | |
unshare |
charmiq:// URI — most commonly the document you're working in — this server is self-contained: list, grant, and revoke without a VFS round-trip. You only need the VFS server when you have to discover the item first (list_dir, semantic_search).charmiq:// URIs from the VFS server — charmiq://workspace/<id>, charmiq://folder/<id>, charmiq://file/<id>.Deltas, Not Replacement
share and unshare are deltas. They change only the users you name and leave everyone else's access exactly as it was. This differs from the web Share dialog, which sends the whole access list at once.share(uri: "charmiq://workspace/abc", grants: [{ user: "u_123", role: "editor" }]) → u_123 becomes an editor; every other user keeps their existing role
unshare(uri: "charmiq://workspace/abc", user: "u_123")
user:unshare(uri: "charmiq://workspace/abc")
Rules
You must be an Owner of an item to change its sharing (a Manager for folders). shareand revoking another user both require it.Leaving is always allowed. unsharewith nouserremoves you regardless of your role — useful for declining access to something shared with you.At least one Owner. The last Owner cannot be removed; the call fails rather than orphan the item. Folders propagate. Sharing a folder grants the same access to everything inside it. Inherited access can't be revoked on a child. If a user has access through a parent folder, change it on the folder — not on the child item. Email = external invite. Identify a user by UserIdentifierfor an existing platform user, or by email address to share with (and invite) someone not yet on the Platform. By defaultsharesends a notification to added users and an invite to added emails; passnotify: falseto suppress both.
Reading Current Shares
list_shares returns who currently has access to an item and at which role (requires at least Viewer access):list_shares(uri: "charmiq://workspace/abc") → { uri: "...", shares: [ { user: "u_owner", role: "owner" }, { user: "u_123", role: "viewer" } ] }
describe_file in verbose mode, alongside the document's structure and content preview — useful when you want the full picture of an item in one call:describe_file(uri: "charmiq://workspace/abc", verbose: true) → { ..., shares: [ { user: "u_owner", role: "owner" }, { user: "u_123", role: "viewer" } ] }
Patterns
List, then change. Read the current access with list_sharesbefore a grant or revoke so you know the starting state — though, because the tools are deltas, you only ever name the users you intend to change.Grant several at once. shareaccepts multiplegrantsin one call: "share with Ana as editor and Ben as viewer" is a single request.Sharing is not publishing. To make a document visible to a whole audience (Public, Marketplace) rather than to named users, use the Publish server.
Next Steps
charmiq:// URI and read current shares via describe_file.