Docs / The MCP server

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.

ToolDoesAnnotation
carbon_overviewWorkspace overviewThe README (the workspace's own instructions), the full folder tree and the most recently changed documents. Start here.read-only
carbon_listList a folderFolders and documents inside a folder, in the order people arranged them; uploaded files carry their type and size.read-only
carbon_readRead documentsOne or more documents with their version and updated_at; a file comes back as a one-hour download link.read-only
carbon_searchSearch documentsFull-text search with snippets, optionally inside one folder.read-only
carbon_writeCreate or replace a documentWrites a whole document; folders are created on demand; expected_version refuses a stale write.destructive (overwrites)
carbon_editEdit part of a documentReplaces one exact passage; old_text must occur exactly once unless replace_all.destructive (modifies)
carbon_appendAppend to a documentAdds text to the end, creating the document if needed. Good for logs and running notes.non-destructive write
carbon_moveMove or renameMoves or renames a document or a whole folder.destructive (modifies)
carbon_deleteDeleteArchives a document, or a folder and its documents; a person can restore from Deleted documents.destructive
carbon_historyDocument historyLists 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; .md is 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_edit or carbon_append over rewriting a whole document, and pass a short message saying why. The message appears in the workspace's activity and history.
  • carbon_read returns a version; carbon_write accepts expected_version and 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 initialize that 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 with Retry-After beyond 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.