# How to Add an MCP Server to Claude Code on Mac

> The exact claude mcp add syntax for local and remote servers, the three scopes, and how to check a server is connected.

- Canonical URL: https://getedith.pro/guides/add-mcp-server-claude-code
- Published: 2026-11-15
- Updated: 2026-11-15

## 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](https://getedith.pro/extensions/agent-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.json` file 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 notion
```

Inside 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](https://code.claude.com/docs/en/mcp) 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](https://getedith.pro/mcp) page lists what it exposes.

1. 1
   ### Add it with Claude Code's own command
   This is a normal stdio server in user scope, pointing at the `ed` binary inside the app.
   `claude mcp add --scope user edith -- /Applications/Edith.app/Contents/MacOS/ed mcp`
2. 2
   ### Or register every agent at once
   `ed mcp install` edits each client's settings file directly: Claude Code, Codex, Cursor and VS Code. Run it with `--dry-run` first to see the exact entry. It changes only the `edith` entry, keeps a `.edith-backup` copy of the file, and leaves a file it cannot parse untouched.
   `ed mcp install --client all --dry-run`
3. 3
   ### Restart the client and check
   Restart Claude Code, type `/mcp`, and look for `edith`. From a terminal, `ed mcp status` reports each client.
   `ed mcp status`
4. 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 skills install edith-remote-work --agent claude-code --yes`

```
 ed mcp install --client claude
 ed skills ls
 ed skills preview edith-remote-work
```

Destructive tools preview first

Edith's MCP tools keep the command line's safety rules. A tool that changes or removes something returns a preview until the call passes `confirm`, and a call that slips `--yes` into its arguments is refused. Tools exist only for extensions you have turned on, and the agent starts by calling `edith_catalog` to see what is available.

## What Claude can do once it is connected

With Edith connected, you can ask Claude Code to check its own limits through [Usage](https://getedith.pro/extensions/claude-code-usage), run a command on a server you added in [Machines](https://getedith.pro/extensions/ssh-machines), or install an extension, which it will preview and ask you about before confirming. The [Claude Code on Mac](https://getedith.pro/agents/claude-code) page has more, and [running multiple Claude Code agents](https://getedith.pro/guides/run-multiple-claude-code-agents-mac) 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.

## Edith extensions used

- [Claude Code, Codex and Cursor Skills for Mac](https://getedith.pro/extensions/agent-skills): Teach your coding agents how to use Edith with one-click skills.
- [Claude Code Usage Tracker for Mac: Codex, Cursor](https://getedith.pro/extensions/claude-code-usage): See what your coding agents cost and how close you are to their limits.
- [SSH Server Manager for Mac With Docker and Files](https://getedith.pro/extensions/ssh-machines): Watch, browse and run your servers and containers from one place.

## Related guides

- [How to Check Claude Code Usage Limits on Mac](https://getedith.pro/guides/check-claude-code-usage-limits): Check Claude Code usage limits on your Mac with /usage, claude.ai settings and the status line, or keep the 5-hour and weekly limits in the menu bar.
- [How to Run Multiple Claude Code Agents on Mac](https://getedith.pro/guides/run-multiple-claude-code-agents-mac): Run several Claude Code agents in parallel on a Mac with git worktrees and agent view, then watch every agent on one board and answer the blocked ones.
