# Connect an agent Add the Entz connector to Claude Code, Codex, Gemini CLI, Cursor, VS Code, Zed, Claude Desktop or another MCP client, check that it works, and see who the agent is when it opens your documents. `entz-mcp` is a small program that your MCP client starts on your computer and talks to over standard input and output. It needs Node.js 22.3 or later (`node --version` in a terminal tells you which you have). There is nothing else to install: the client runs it with `npx`, which downloads it the first time and reuses it afterwards. The connector shows the agent to people as **Claude** unless you give it another name with `ENTZ_AGENT_NAME`. With any other agent, set it to that agent's name, as the examples below do, so people see who is writing. The [environment variables](#environment-variables) at the end of this page list the other settings. ## Command-line agents ### Claude Code ```sh claude mcp add entz -- npx -y entz-mcp ``` That adds the connector for you, in the current project. Add `--scope user` to have it in every project, or `--scope project` to share it with everyone who works in the project (Claude Code writes it to the project's `.mcp.json`). Environment variables go after the name, one `-e` for each: ```sh claude mcp add --scope user entz -e ENTZ_OPEN=0 -- npx -y entz-mcp ``` Start a new Claude Code session after adding it. Claude Code asks your permission before its agent uses the connector's tools, as for any MCP server. ### Codex CLI ```sh codex mcp add entz --env ENTZ_AGENT_NAME=Codex -- npx -y entz-mcp ``` Codex keeps its servers in `~/.codex/config.toml`, where the same entry reads: ```toml [mcp_servers.entz] command = "npx" args = ["-y", "entz-mcp"] [mcp_servers.entz.env] ENTZ_AGENT_NAME = "Codex" ``` ### Gemini CLI Gemini CLI reads its servers from `~/.gemini/settings.json` (every project) or `.gemini/settings.json` (one project): ```json { "mcpServers": { "entz": { "command": "npx", "args": ["-y", "entz-mcp"], "env": { "ENTZ_AGENT_NAME": "Gemini" } } } } ``` ## Editors ### Cursor Cursor reads its servers from `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project): ```json { "mcpServers": { "entz": { "command": "npx", "args": ["-y", "entz-mcp"], "env": { "ENTZ_AGENT_NAME": "Cursor" } } } } ``` ### VS Code VS Code keeps a workspace's servers in `.vscode/mcp.json`, under `servers` rather than `mcpServers`: ```json { "servers": { "entz": { "type": "stdio", "command": "npx", "args": ["-y", "entz-mcp"], "env": { "ENTZ_AGENT_NAME": "Copilot" } } } } ``` To add it for every workspace instead, run this in a terminal: ```sh code --add-mcp "{\"name\":\"entz\",\"command\":\"npx\",\"args\":[\"-y\",\"entz-mcp\"]}" ``` ### Zed Zed takes the connector in its settings file, under `context_servers`: ```json { "context_servers": { "entz": { "command": "npx", "args": ["-y", "entz-mcp"], "env": { "ENTZ_AGENT_NAME": "Zed" } } } } ``` ## Desktop apps ### Claude Desktop Claude Desktop reads its servers from `claude_desktop_config.json`: choose **Settings…** from the Claude menu, then **Developer**, then **Edit Config**. The file lives at: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` Add the connector under `mcpServers`, beside any servers already there: ```json { "mcpServers": { "entz": { "command": "npx", "args": ["-y", "entz-mcp"] } } } ``` Quit Claude Desktop completely and open it again: it starts its servers only when it launches. ## Other MCP clients Any client that starts a local server over standard input and output can run the connector: the command is `npx`, the arguments are `-y` and `entz-mcp`, and the environment variables are optional. Most take the `mcpServers` shape shown for Cursor, in a file of their own; the client's documentation says which. ## Who the agent is in Entz The connector has no sign-in of its own, and Entz has no screen that hands out a token for it yet. So it connects to entz.app without signing in, and Entz gives it an identity of its own: a new one each time the connector starts, which the People list under **Access…** marks as anonymous. The agent reaches documents through their links, the way anyone you send a link to does. - **Documents the agent creates** belong to that identity. Their link starts out open to anyone, with **Edit**, so when you open one you join it as an editor and it stays in your library. - **Your documents** open for the agent at the permission their link gives under **Access…**: with **Edit** it writes, with **Comment** it reads and comments, with **View** it only reads. With **Anyone with the link** off, the agent cannot open the document unless it joined before. [Sharing and access](/docs/sharing/) explains the sheet. - **Each start is a new identity.** A document the agent made in an earlier session is no longer its own: it opens it through the link like anyone else, with the link's permission at that moment. You need to be signed in to Entz to see what the agent opens for you. Signed out, a link it opens in your browser goes back to [your library](/docs/library/) with the words "Sign in to open this document"; the document waits there and opens once you sign in (**Settings**, **Connection**, **Sign in**; see [Settings](/docs/settings/)). Since a document the agent created is not yours, you cannot change who its link admits or delete it for everyone: **Delete** only takes it off your list. When that matters, make the document yourself, choose **Copy link** from its menu and give the agent the link. For a document the agent already made, open it and choose **Make a copy** from its menu: the copy of its main tab is yours, without the other tabs and the comments. ## Environment variables | Variable | Default | What it does | |---|---|---| | `ENTZ_AGENT_NAME` | `Claude` | The name people see on the agent's avatar, caret and comments. Set it to your agent's name when that is not Claude. | | `ENTZ_AGENT_COLOR` | `#d97757` | The colour of the agent's avatar and caret, as `#rrggbb`. | | `ENTZ_OPEN` | on | `0` keeps your browser closed: the agent gives you links instead. Otherwise each new document opens in your default browser as soon as its outline is in, and any document you ask the agent to show opens there too. | | `ENTZ_TOKEN` | none | A token for an Entz identity to act as instead of an anonymous one. Entz does not hand out tokens yet, so leave it unset. | | `ENTZ_APP_URL` | `https://entz.app` | Where the links the agent gives and opens point. Leave it alone for entz.app. | | `ENTZ_URI`, `ENTZ_DB` | entz.app's server | Leave these alone for entz.app. | ## Check that it works Look for `entz` among your client's servers: - in Claude Code, Codex and Gemini CLI, run `/mcp`; - in VS Code, run **MCP: List Servers** from the Command Palette; - in Zed, open **Settings**, **AI**, **MCP Servers**, where a green dot means it is running; - in Claude Desktop, open the add menu at the bottom left of the message box and point to **Connectors**. Its eight tools are `guide`, `create`, `open`, `read`, `update`, `tabs`, `comments` and `export`. Then ask for something small: ```text Create an Entz document called "Connector check" with a heading and a three-item checklist. ``` The agent creates the document and your browser opens it at entz.app. If Entz says to sign in, sign in and open the document from your library. Its words fade in as they arrive. Ask the agent to tick the first item, and the checkbox changes while you watch. If something does not work, see [Troubleshooting](/docs/mcp/troubleshooting/).