Claude Code
After this page, Claude Code starts email-mcp, an MCP (Model Context Protocol)
server, and can use its tools. The agent is the AI (artificial intelligence)
program that uses these tools. A tool is one action that the agent can call,
such as search_messages.
Source and date
Source: https://code.claude.com/docs/en/mcp, checked on 2026-10-29. The
command claude mcp remove is on the same page, checked on 2026-11-06.
The command claude --version is in the CLI reference of Claude Code:
https://code.claude.com/docs/en/cli-reference, checked on 2026-11-06.
Add email-mcp (stdio)
Run this in a terminal. The command adds email-mcp to Claude Code under the
name email. --scope user makes the server available in every project.
Everything after -- is the command that Claude Code runs. email-mcp serve
talks MCP over stdio (standard input and output: Claude Code starts the program
and talks to it directly, with no network).
claude mcp add --scope user email -- email-mcp serve
Start Claude Code. The command /mcp shows whether the server is connected.
If Claude Code cannot find email-mcp, give it the absolute path of the program
as the command. An absolute path is the full path of a file. The command
which email-mcp shows it (use where email-mcp on Windows). If you added the
server before, remove it first with claude mcp remove email. The path in this
command is an example:
claude mcp add --scope user email -- /opt/homebrew/bin/email-mcp serve
If your master key is a file
Use this only when your master key (the key that protects your stored passwords) is a file. By default, the master key is in the keychain (the password store of your operating system), and you need nothing more.
With a key file as the master key, this command also sets the environment
variable (a named setting that a program reads from its surroundings)
EMAIL_MCP_KEK for the server. KEK means key encryption key. --env sets the
variable, and --transport stdio says that Claude Code starts the server as a
program. The value file: says that the master key is in a file, and the
absolute path of the key file follows. The path in the command is only an
example: use the path of your own key file. On macOS it can look like
/Users/you/.email-mcp.key. To see which master key you use, run
email-mcp doctor: its line shows master key (keychain) or
master key (file:...):
claude mcp add --scope user --env EMAIL_MCP_KEK=file:/home/you/.email-mcp.key \
--transport stdio email -- email-mcp serve
Keep another flag, such as --transport stdio, between --env and the server
name. Otherwise Claude Code reads the name as another variable. As before, the
command /mcp shows whether the server is connected.
Local HTTP
Use stdio when the app supports it. Use local HTTP only for an app that cannot start a program (see Local HTTP mode). HTTP (HyperText Transfer Protocol) is the protocol that apps and browsers use to talk over a network. With local HTTP, email-mcp runs a small server on your own computer, and Claude Code connects to it with a token (a secret that Claude Code sends to the server). Do these three steps in order.
If your master key is a file, set the environment variable EMAIL_MCP_KEK in
each terminal where you run step 1 or step 2 (step 2 runs in its own terminal).
Use the same value as in the config of your AI app. For example, on macOS and
Linux, export EMAIL_MCP_KEK=file:/Users/you/.email-mcp.key sets it for that
terminal (the path is an example). Without it, the two commands look for the
master key in the keychain.
-
Make a token.
--nameis a name for the token, such as the app that uses it.--scopessays what the token allows. A scope is one permission of a token. The scopes areemail:read,email:organize,email:draft,email:sendandemail:delete(moves mail to the Trash), orall. Scopes add up: each scope also allows the ones before it, soemail:sendalso allows reading, organizing and drafting. Give only the scopes that the app needs. Useemail:readto let the agent only read mail, andemail:sendto let it also send. The command needs both flags:email-mcp token create --name claude-code --scopes email:sendThe command prints the token: a text that starts with
emcp_. Copy it now. It is shown only once. -
Start the server.
--httpgives the address where the server listens. The address must be a loopback address (an address that only your own computer can reach), such as127.0.0.1. The number after the colon is the port (the number that names one service on an address):email-mcp serve --http 127.0.0.1:8765The server prints a log line that says “serving MCP over local HTTP”, with the address and the path
/mcp. It must keep running as long as Claude Code uses it. Run it in its own terminal, and keep that terminal open. If it says that the address is already in use, use another port number here and in the address of step 3. -
Add the server to Claude Code.
--transport httpsays that Claude Code connects over HTTP.--headeradds a header (an extra line of information) with your token to every request. InAuthorization: Bearer <token>, a bearer token is a token that works for anyone who holds it. Replace<token>with the token of step 1:claude mcp add --transport http --scope user email \ http://127.0.0.1:8765/mcp --header "Authorization: Bearer <token>"
To get the form in Claude Code instead of the approval link (a link to a web
page where you approve or reject the send), add --in-band-confirm to the
command of step 1: email-mcp token create --name claude-code --scopes email:send --in-band-confirm. Any program with the token can then answer for
you.
With --header, Claude Code stores the token in plain text in
~/.claude.json. To keep it out of that file, use a
headersHelper: a command that Claude
Code runs at each connection, and that prints the headers as JSON (JavaScript
Object Notation: a text format for data). The Claude Code docs describe it in
the section “Use dynamic headers for custom authentication”. This one reads
the token from the environment variable EMAIL_MCP_TOKEN, which you set in
the shell that starts Claude Code (for example from your password manager):
claude mcp add-json --scope user email '{"type":"http","url":"http://127.0.0.1:8765/mcp","headersHelper":"printf '"'"'{\"Authorization\":\"Bearer %s\"}'"'"' \"$EMAIL_MCP_TOKEN\""}'
claude mcp list then shows the server as connected when EMAIL_MCP_TOKEN is
set, and as refused (HTTP 401) when it is not.
Confirmation
- Claude Code shows elicitation forms in a dialog. Elicitation is a way for a
server to ask the person a question through the app. The docs say that it
declares form and URL (web address) elicitation on connections that use
protocol 2026-07-28, and on the stdio and HTTP servers of your own MCP config
on older protocol versions (Claude Code v2.1.287 or later). To see your
version of Claude Code, run
claude --versionin a terminal. A protocol version is a date. It names the version of the MCP rules that the app and the server use. - In a non-interactive session (a run with no person at the keyboard, such as
claude -p), Claude Code does not show the form. It asks the server to cancel instead, so the send is declined. - Do not add an
Elicitationhook (a script that Claude Code runs when an event happens) that answers the form automatically. It would turn the confirmation off.
The page How each AI app confirms compares the five apps.
Recommended deny rules
Also add the recommended deny rules (see the page Recommended Claude Code deny rules).
Next: Your first use