Clearly MCP server

Clearly

Your workspace, addressable by agents. Documents, canvases, slides, sheets, projects and tickets — reachable over MCP from any client, and from a terminal.

• Website — clearly.sh
• MCP docs — clearly.sh/docs/mcp
• MCP Registry — sh.clearly/clearly

This repository has no source code. It is the public home for **issues, release notes and

security reports**. Clearly is a hosted service; the server runs on our infrastructure and the

CLI is distributed as a build. If you are looking for a place to file a bug or ask what changed

in a release, you are in the right place.

MCP

Clearly is an MCP server, not a plugin — your agent connects out to it.

https://relay.clearly.sh/mcp

Authentication is OAuth 2.1 with dynamic client registration (RFC 7591), so most clients need nothing but the URL. Sign-in asks which workspace and which agent the connection acts as.

Claude Code

claude mcp add --transport http clearly https://relay.clearly.sh/mcp
claude mcp login clearly

There is also a Claude Code plugin that bundles the connector with a set of skills.

Other clients

Any client that speaks streamable HTTP MCP can connect to the same URL. Configuration differs — Claude Desktop and Cursor use mcpServers, VS Code uses servers with "type": "http", and Codex reads its bearer from an environment variable. The MCP docs carry a snippet per client.

Holding more than one workspace or agent at once

A client stores one credential per server entry, so two workspaces behind a single entry collide. Two extra path forms exist for that reason — each is a distinct credential key:

The agent segment is addressing, never authority — the server refuses it unless it matches the token's own agent.

Protocol

Streamable HTTP. The server negotiates and echoes the client's requested protocol revision, and supports 2025-06-18, 2025-03-26 and 2024-11-05.

CLI

curl -fsSL https://clearly.sh/install.sh | sh

The installer writes beehaven to ~/.local/bin (override with BEEHAVENBINDIR).

Read it before you run it — install.sh is a plain shell script. Being precise about what it does, since piping to a shell deserves that: it downloads a release tarball from downloads.clearly.sh over HTTPS and runs npm install inside it to build the native dependencies (better-sqlite3, node-pty) for your platform. It does not verify a signature or a checksum today — your trust is in TLS and in us. Node 20+ is required and the script checks for it first.

beehaven login                       # authenticate
beehaven connect home                # pick a workspace
beehaven ls ~                        # your documents, as files
beehaven grep -ril pricing ~         # search them
beehaven call <action> '{...}'       # any workspace action
beehaven status                      # connection + auth state

beehaven --help lists the rest.

Reporting things

• Bugs and feature requests — open an issue.
• Security — please do not open a public issue. See SECURITY.md.

Shortened. The full README is on GitHub.