Local agents (cellucid mcp)#

cellucid mcp is a local MCP server over stdio for an agent app on this computer (Claude Code, Claude Desktop, Cursor): the app works in a Cellucid viewer with the web app’s tools, under the permissions set in the viewer. The app starts it; set-up, what you see and decide, and privacy are in Local agents (MCP): Claude Code, Claude Desktop, Cursor. It needs the mcp extra:

pip install 'cellucid[mcp]'

The command (cellucid mcp, CLI (cellucid)) and run_mcp() are the same server; run_mcp is what the command calls, for an app that starts Python itself:

{"mcpServers": {"cellucid": {"command": "python", "args": ["-c", "from cellucid.mcp import run_mcp; run_mcp()"]}}}

  • Tools: every action of the viewer, generated from the web app’s action catalogue exactly as the Cellucid connector lists them (names, input schemas, descriptions, annotations), plus cellucid_status. While a viewer page is open, its own list for this connection is used: each description says what your permission settings make of it.

  • Calls run in the viewer page as the app’s agent (“Claude Code”), through a connection of kind local (“Claude Code (local)” in the viewer). A question the person is asked is the viewer’s confirm card and, when the app declares the elicitation capability, an elicitation in the app. A call the app cancels (notifications/cancelled) is stopped in the viewer.

  • Results of the viewer’s tools are the connector’s: the data between <cellucid-data> and </cellucid-data> (every < inside escaped), Cellucid’s own sentences after it, a refusal in one sentence, and a dataset’s “Agents see names and summaries only” switch applied by the page (Permissions and what agents see).

  • Output: stdout carries only MCP messages; everything else (the --open viewer’s address, why no viewer is reachable) is said on stderr.

cellucid.mcp.run_mcp(open=None, *, viewer=None, port=None, open_browser=True, web_source_url=None, web_cache_dir=None)[source]#

Run cellucid mcp on this process’s stdin and stdout until the app closes them.

Parameters:

  • open (str | Path | None) – A file or folder to serve and open in a viewer of this process (any format Cellucid reads); its page opens in the browser, and the viewer stops when the server ends. None drives a viewer opened elsewhere on this computer.

  • viewer (str | None) – Which published viewer to drive (its viewer id, dataset id or dataset name); None takes the most recently opened one whose page is open. Ignored with open.

  • port (int | None) – The port of the viewer open starts (None: 8765, or the next free one).

  • open_browser (bool) – Whether open opens the viewer’s page in the browser (False: its address is printed on stderr).

  • web_source_url (str | None) – Where the viewer’s page is loaded from (default: https://www.cellucid.com).

  • web_cache_dir (str | Path | None) – Where the viewer keeps its copy of the page.

Return type:

None

On this page