The Carbon MCP server
A remote MCP server over streamable HTTP. Every connected tool gets the same ten actions over one workspace, with every change attributed and versioned.
Endpoint
https://www.carbon.app/api/mcp
Streamable HTTP, stateless, JSON responses (a GET on the endpoint answers 405, as the specification allows). Any client that supports remote MCP servers can use it. There is nothing to install.
Authentication
Sign in (OAuth 2.1). Clients that implement MCP authorization need no configuration: an unauthenticated request answers 401 with a WWW-Authenticate header pointing at the protected-resource metadata, which names the authorization server. Dynamic client registration is open, PKCE (S256) is required, refresh tokens rotate, and the person picks the workspace on a consent screen that also names where they will be sent back. This is how Claude, ChatGPT and Grok connect.
https://www.carbon.app/.well-known/oauth-protected-resource https://www.carbon.app/.well-known/oauth-authorization-server https://www.carbon.app/oauth/register (RFC 7591) https://www.carbon.app/oauth/authorize (code + PKCE S256) https://www.carbon.app/oauth/token (authorization_code, refresh_token)
Keys. Clients without OAuth (Cursor, Claude Code with a header, scripts) send a bearer key created from Connect AI tools in the workspace. A key is shown once and stored only as a hash; it can be read-only; it can be revoked at any time.
Authorization: Bearer carb_…
Tools
Every tool has a title, a description that says when to use it, and explicit annotations (read-only, destructive, open-world) so a client can decide what to confirm with the person. All tools are closed-world: they act only inside the connected workspace.
| Tool | Does | Annotation |
|---|---|---|
carbon_overviewWorkspace overview | The README (the workspace's own instructions), the full folder tree and the most recently changed documents. Start here. | read-only |
carbon_listList a folder | Folders and documents inside a folder, in the order people arranged them; uploaded files carry their type and size. | read-only |
carbon_readRead documents | One or more documents with their version and updated_at; a file comes back as a one-hour download link. | read-only |
carbon_searchSearch documents | Full-text search with snippets, optionally inside one folder. | read-only |
carbon_writeCreate or replace a document | Writes a whole document; folders are created on demand; expected_version refuses a stale write. | destructive (overwrites) |
carbon_editEdit part of a document | Replaces one exact passage; old_text must occur exactly once unless replace_all. | destructive (modifies) |
carbon_appendAppend to a document | Adds text to the end, creating the document if needed. Good for logs and running notes. | non-destructive write |
carbon_moveMove or rename | Moves or renames a document or a whole folder. | destructive (modifies) |
carbon_deleteDelete | Archives a document, or a folder and its documents; a person can restore from Deleted documents. | destructive |
carbon_historyDocument history | Lists saved versions, or returns one version's content. | read-only |
How the server expects tools to behave
- Paths, never ids:
projects/atlas/decisions.md. Folders are implicit and created on demand;.mdis added when an extension is missing. - Start with
carbon_overview: the README is the workspace's own instructions. Read a document before editing it. - Prefer
carbon_editorcarbon_appendover rewriting a whole document, and pass a short message saying why. The message appears in the workspace's activity and history. carbon_readreturns a version;carbon_writeacceptsexpected_versionand refuses a stale write, so two tools editing the same document cannot silently clobber each other.- Uploaded files (images, PDFs, anything that is not text) are listed with
kind: "file"; reading one returns a one-hour download link; writing text into one is refused with a sentence. - Errors are plain sentences a tool can act on, never a bare status code: what was wrong and what to do instead.
- The server sends instructions on
initializethat name the workspace, the connection, and these rules.
Limits and privacy
- Free plan: 120 requests a minute and 10,000 a day per connection, with
X-RateLimit-*headers on every response and a 429 withRetry-Afterbeyond them. Documents up to 1 MB; files up to 20 MB; 1 GB per workspace. - The server reads nothing from a conversation beyond the arguments of the tool being called, and stores nothing about the client beyond the connection's name and when it was last used.
- Everything a workspace holds can be exported as a zip at any time, and deleted for good from Settings.
Questions: hello@carbon.app. Policies: privacy, terms. The same operations are available as a REST API.