Skip to main content

​
Overview

Cleve exposes an MCP (Model Context Protocol) server at:
Once connected, your agent gets read/write access to the same workspace your team uses — notes, folders, skills, memory, and org context. Authentication is handled via OAuth on the first connection. You’ll be prompted to sign in with your Cleve account; no manual token management required.

​
Connect to Cleve

Follow the Cleve MCP connection guide for Claude, ChatGPT, and other agents. You can also find it in Settings → Integrations → Connect your AI (MCP) inside Cleve.

​
Available Tools

Every notes, folder, and skill tool also accepts an optional organization parameter: the id or exact name of the workspace to act in. See Workspaces for how the workspace is chosen when you omit it.

​
Notes

​
Folders

​
Skills Marketplace

​
Web Content

This tool requires an authenticated MCP connection but does not accept organization or read workspace notes.

​
Memory

​
Workspaces

Each call runs in exactly one workspace, chosen in this order:
  1. The organization parameter on the call, matched exactly by id or by name (case-insensitive).
  2. The workspace saved for this MCP client with cleve_switch_org. Selections are stored per client, so Claude Code and Cursor can target different workspaces on the same account, and they persist until you switch again.
  3. Your only workspace, if you belong to just one.
If you belong to several workspaces and none of the above applies, the tool returns an error listing your workspaces instead of guessing. Agents also receive this guidance in the server’s instructions when they connect, so they know to call cleve_list_orgs first.

​
Sharing and Publishing

Cleve separates three actions:
  • Share access: invite specific people by email, or let anyone with the link view or edit the note. This does not list it on your profile or create a marketplace item.
  • Publish to the web profile: cleve_publish_note makes the note a publicly readable post on the owner’s Cleve profile, like a blog post. Only the owner can publish, and a profile username must be set up first. If it is missing, the tool returns an error with a clickable username-setup link and a structured setupUrl pointing to General settings. Ask the user to set a username there, then retry publishing.
  • Publish to the marketplace: cleve_publish_note_template creates and publishes a separate template copy that anyone can discover and install. It preserves the source editor snapshot and rich formatting when available. Later edits to the source note do not update the template, and the source note’s access and web-profile publication stay unchanged. The returned itemId identifies the marketplace copy, not the source note.
Start with cleve_get_note_sharing. It returns the owner’s ownerUserId, canManageSharing, profile-publication status, collaborators (with userId, direct or folder-inherited access), invitations (with _id and expiry), pending requests (with _id) and sharing activity. Invite, request and activity details are available only to people who can manage sharing. Link access includes direct and effective roles (viewer, editor, or null), plus publishedViaFolder, so an inherited grant is not mistaken for a restricted note. Use cleve_set_note_link_access with access: "restricted", "viewer", or "editor" to match General access in the dialog. Editing requires sign-in. The existing cleve_share_note remains compatible: isPublic: true sets the note’s own link to viewer, including downgrading an editable link; false restricts only its own link. Both tools leave collaborators, workspace access, inherited folder grants and profile publication unchanged. Removing a direct collaborator does not remove folder or workspace access; inherited grants must be managed at their source. cleve_get_note_link is the equivalent of Copy link. It returns the canonical /notes/<noteId> URL without making anything public. A restricted recipient must already have access or request it. Do not enable sharing just to return a URL. Email sharing returns invited: true when the recipient has not joined Cleve yet; this is a pending invitation, not immediate access. Use the invitation _id to resend or withdraw it. Ownership transfer is a separate handover, not an editor permission: the recipient must already have access, and the previous owner retains editor access. Approving or denying a request uses its _id and may notify the requester by email. Unpublishing removes the note’s own web-profile publication. It does not disable link sharing, remove collaborators, unpublish a folder, or remove marketplace copies. Restricting a link or unpublishing alone must not be described as making a note private.

​
Comments

These tools operate on Cleve comment threads, not arbitrary API requests. Each accepts the optional organization parameter described in Workspaces. They change comments or thread status, not the note’s document content.

​
Add a Comment

cleve_add_comment creates an AI comment anchored to a passage in a note. It requires:
  • noteId: the ID of an accessible note.
  • quote: text copied verbatim from the note. It must match exactly once; a missing or ambiguous passage returns an error. A longer quote can disambiguate repeated text.
  • body: the comment text, in plain prose.
Read the note with cleve_view_note or cleve_read_note before choosing the quote. The passage is highlighted in the editor, and the thread appears in the comments sidebar. A successful response includes success: true, the created threadId, and quotedText.

​
Reply to a Comment

cleve_reply_to_comment adds a reply to a comment thread and leaves it open. It requires threadId and body. Obtain the thread ID from cleve_list_note_comments or cleve_view_note. A successful response contains success: true and the threadId. Replying does not edit the note or mark the thread resolved.

​
Resolve a Comment

cleve_resolve_comment marks a thread resolved. It requires threadId and optionally accepts body for a closing reply. A successful response contains success: true and the threadId. Resolving does not perform the edit requested in a comment. If an edit is needed, make it with a note-editing tool before resolving the thread.

​
Installing Skills

cleve_install_skill supports two sources:
  • Cleve marketplace: pass skillId from cleve_search_marketplace to install that skill.
  • SKILL.md import: pass url containing a GitHub owner/repo, a GitHub repository or skill-folder URL, a skills.sh page, or a direct HTTPS link to a SKILL.md file. Cleve downloads and imports the skill into your account.
For a repository containing multiple skills, slugs selects the skill names to import; omit it to import all valid discovered skills. slugs only filters repository-based imports. Provide either skillId or url. If both are supplied, url takes precedence. A call with neither returns an error. The marketplace path returns a success message; the URL-import path returns details of the imported skills. Installation changes saved skill data; URL imports also fetch content from the supplied external source. Installing a skill does not execute its instructions. Treat third-party skill content as untrusted and review it before use. Like other skill tools, this tool accepts the optional organization parameter.

​
Fetching URLs

cleve_fetch_url reads a public HTTP or HTTPS URL. It extracts the main content of HTML pages as Markdown and returns text-based files as text. Binary files return a description rather than extracted document content. It does not save a note or send a write request to Cleve. Parameters:
  • url (required): an absolute HTTP or HTTPS URL.
  • maxLength: maximum returned content characters, default 5000, capped at 50000.
  • startIndex: character offset, default 0. Use the returned nextStartIndex to request another page of a long result.
  • raw: default false; set to true to return response text without HTML-to-Markdown extraction. Binary files still return a description.
The returned text includes the requested URL, final URL after redirects when different, content type, title when available, total content length, and pagination information. Downloaded content is explicitly marked as untrusted data, not instructions. Private, local, and internal network destinations are blocked, including redirects to those destinations. This tool does not use your Cleve session to sign in to external websites and has no caller-supplied headers, HTTP method, or request-body parameter. It is a web-content reader, not a general-purpose REST API client.

​
Authentication Details

The MCP server uses OAuth 2.0 via Clerk. On first connect:
  1. Your client opens the Cleve authorization URL
  2. You sign in with your Cleve account
  3. Your client stores the access token and sends it as a Bearer header on every request
The server reads your user identity and workspace memberships from the token. You do not need an API key for MCP — it’s separate from the REST API key system. If you belong to multiple workspaces, use cleve_list_orgs to see them and either pass organization on each call or use cleve_switch_org to save a default for the client you are connecting from.

​
Example Prompts