The short answer
Run claude mcp add in your terminal. For a server that runs as a local program, put its command after --. For a remote server, pass --transport http and its URL. Then type /mcp inside Claude Code to confirm it connected. This guide covers the syntax, the scopes, and how to connect Edith's own MCP server, plus the Claude Code skills that teach Claude how to use it.
Adding a local (stdio) server
Built into Claude Code
claude mcp add with --
A stdio server is a program Claude Code starts and talks to over standard input and output. The form is claude mcp add [options] <name> -- <command> [args...]. Everything after -- goes to the server untouched, so flags meant for the server are not read as Claude Code options.
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server
claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080--env, or -e, sets environment variables for the server and accepts several KEY=value pairs. Put another option between --env and the server name, as in the examples, so the name is not read as one more variable.
Adding a remote (HTTP) server
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer your-token"--header, or -H, sends a request header such as a token. Servers that use OAuth sign you in from the /mcp screen inside Claude Code. The SSE transport still exists for older servers but Anthropic marks it as deprecated in favour of HTTP.
Choosing a scope
--scope, or -s, decides who sees the server:
- local, the default: only you, only in the current project. Stored in
~/.claude.json. - project: everyone working in the project, through a
.mcp.jsonfile at the project root that you commit. - user: only you, in every project. Also stored in
~/.claude.json.
A tool that works on your whole Mac, rather than one repository, belongs in user scope.
Checking and removing servers
claude mcp list
claude mcp get notion
claude mcp remove notionInside a session, /mcp shows each server's status, handles OAuth sign-in, and with /mcp reconnect all retries servers that failed. If you already have a JSON definition, claude mcp add-json takes it directly. Anthropic's MCP documentation covers every flag.
Where it gets awkward
- Every client is different. Claude Code stores servers in
~/.claude.json, Codex in~/.codex/config.toml, Cursor in~/.cursor/mcp.json. Adding one server to three agents is three different edits. - You need the exact command. A wrong path to the server binary fails quietly until you open
/mcp. - Tools are not instructions. A server gives Claude tools, but not the habits for using them well, such as previewing a destructive action before running it.
The Edith way: one command for every agent
Edith ships an MCP server inside the app. Every ed command becomes a tool named after its route, so ed usage limits is edith_usage_limits and ed machines ls is edith_machines_ls. The Edith MCP server page lists what it exposes.
- 1
Add it with Claude Code's own command
This is a normal stdio server in user scope, pointing at the
edbinary inside the app. - 2
Or register every agent at once
ed mcp installedits each client's settings file directly: Claude Code, Codex, Cursor and VS Code. Run it with--dry-runfirst to see the exact entry. It changes only theedithentry, keeps a.edith-backupcopy of the file, and leaves a file it cannot parse untouched. - 3
Restart the client and check
Restart Claude Code, type
/mcp, and look foredith. From a terminal,ed mcp statusreports each client. - 4
Teach Claude how to use it
The Plugins extension installs short skill files that tell an agent how to drive Edith. Preview one first, then install it for the agents you choose.
ed mcp install --client claude
ed skills ls
ed skills preview edith-remote-workWhat Claude can do once it is connected
With Edith connected, you can ask Claude Code to check its own limits through Usage, run a command on a server you added in Machines, or install an extension, which it will preview and ask you about before confirming. The Claude Code on Mac page has more, and running multiple Claude Code agents works well with a shared MCP setup in user scope.
Common questions
Why put Edith in user scope rather than project scope?
Edith works on your Mac as a whole, not on one repository, and a project-scope .mcp.json would be committed for teammates who may not have Edith installed.
Do I need ed on my PATH?
No. Both commands above point at the binary inside /Applications/Edith.app, so the server works whether or not ed is linked onto your PATH.