MCP without the hype: what the protocol actually gives you

In Claude Code

The claude mcp add command creates the configuration automatically, and you decide where it lands with the --scope flag:

claude mcp add sentry --transport http --scope user https://mcp.sentry.dev/mcp
claude mcp add wc --scope project -- python3 ./tools/word_count.py

• Everything after the -- is forwarded to the server unchanged

• You can list all your servers using claude mcp list. This command connects with every server and runs a health-check on it, which is the cheapest way of making sure if the server is up (doesn't require the LLM call)

• The tools are accessible via mcp__<server>__<tool> identifier. It's what you need to include in permission rules or hook matchers

By default, a server with project-level scope isn't started until you accept it interactively. For example:

• claude mcp list will display the server as pending approval

wc: python3 ./tools/word_count.py - ⏸ Pending approval (run `claude` to approve)

• It won't run; this is by design, as .mcp.json file can be committed to the repository by another member of your team, therefore whenever you clone a repository, it doesn't have any tools of your teammates until somebody approves them (as described in the docs). At least the pending state shows up in the list output, so it's not a silent one

• You can run claude mcp reset-project-choices to get rid of previous choices and do them again.

Two more things:

• The output limit is 25k tokens by default (you can increase it setting MAX_MCP_OUTPUT_TOKENS env var). Above the 10k threshold it warns you

• Tool search feature is enabled by default, which means that MCP tool definitions are loaded lazily — on session start, the client just knows the names of the tools and the server instructions, and fetches schemas for them only when needed. If you disable it (ENABLE_TOOL_SEARCH=false), the definitions are preloaded. Alternatively, you can set it to auto, which means that the definitions are preloaded if the tools can fit into 10% of the context window. Finally, you can set alwaysLoad: true for a server in the entry, to exclude it from lazy loading

In Codex CLI

codex mcp add modifies ~/.codex/config.toml, creating a TOML table per server. For example, for a local server that is set up from a python script and env var — it is stored there as command/args/env (the env is a nested table):

codex mcp add wc --env WC_LOG=/tmp/wc.log -- python3 ./tools/word_count.py

[mcp_servers.wc]
command = "python3"
args = ["./tools/word_count.py"]

[mcp_servers.wc.env]
WC_LOG = "/tmp/wc.log"

There's another way for remote servers too with url in place of command, and an auth field which can be either "oauth" or with a bearer_token_env_var; sometimes you need to add fixed http headers so there's a place for it too.

Any server can have the following options:

• startup_timeout_sec (defaults to 10s)

• tool_timeout_sec (defaults to 60s)

• enabled_tools/disabled_tools, to only expose a subset of tools from a server

Except for the last one, which is about handling context bloat, the rest are general settings that can be set per server.

The gotcha.

The codex mcp list command shows what is configured; it doesn't connect to anything. After running codex mcp add, you can run codex mcp list and it will show a row like this: name / command / args / env / cwd / status / auth.

Name  Command  Args                  Env            Cwd  Status   Auth
wc    python3  ./tools/word_count.py WC_LOG=*****   -    enabled  Unsupported

And the status is enabled while there's no process started — you can check that because the server's log file hasn't appeared. So this is more about saying it's not disabled in the configuration, not that the server works. In contrast, if you run claude mcp list then it checks the servers health, but these are two different commands so just because they look similar doesn't mean that a table is a good indicator of sth working. The env values are masked too so you can safely share the output in a bug report.

In GitHub Copilot CLI

The copilot mcp command is all about the MCP configuration that the GitHub Copilot CLI offers, it integrates with a variety of sources.

3 levels of configuration, and it says so itself:

User       ~/.copilot/mcp-config.json
Workspace  .mcp.json or .github/mcp.json
Plugin     Installed plugins with MCP servers

For example: adding a server for stdio and another one for remote (HTTP transport):

copilot mcp add wc -- python3 ./tools/word_count.py
copilot mcp add --transport http notion https://mcp.notion.com/mcp

At the user level, you need to have this in the ~/.copilot/mcp-config.json file: the "tools" field is a native feature of this configuration format, it's not an additional thing that's been bolted on. The copilot mcp command has this default for it: [""]. So you can run mcp add and pass the --tools flag with either "" (for all tools), a comma-separated list of names, or an empty string if you want to have zero tools. There's also a configuration entry for a server that illustrates this:

{
  "mcpServers": {
    "wc": {
      "tools": ["*"],
      "type": "local",
      "command": "python3",
      "args": ["./tools/word_count.py"]
    }
  }
}

Permissions use the same names: --allow-tool='MyMCP' for a whole server, --deny-tool='MyMCP(risky_tool)' for one of its tools.

At the workspace level, the .mcp.json file is exactly what Claude Code writes at the project level. If you were to run the GitHub Copilot CLI in a repo that's configured with Claude Code, copilot mcp list --json would return these servers under "source": "workspace" with the file path, including the "type": "stdio" ones which are treated on par with Copilot's "local".

The only downside is that if you have a server with the same name in your user config and in the workspace .mcp.json file, only one of them shows up. In order to avoid confusion, make sure to use different names for servers so that when you have problems you're not wondering why it's not working for one when in fact it's another one.

In Cursor

The configuration is JSON file with the standard structure like for other tools. It's stored either in .cursor/mcp.json in the root of your repo, or in ~/.cursor/mcp.json if you want to set it up globally. For instance:

{
  "mcpServers": {
    "wc": {
      "command": "python3",
      "args": ["./tools/word_count.py"],
      "env": { "WC_LOG": "/tmp/wc.log" }
    }
  }
}

In case of remote servers, you can use url instead of command, and add headers if you need authentication for example:

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:3000/mcp",
      "headers": { "API_KEY": "value" }
    }
  }
}

The tool will ask for your permission to run it by default. Just like for shell commands, it inherits the same run modes (auto-run etc), so you can use the same auto-run option that you were using for these commands if you wish — personally, I prefer it as it's easy to forget about enabling mcp in the config if you add a separate field for it.

The gotcha. The only catch is that cursor-agent doesn't have any mcp subcommand, so there's no list or get, and you can't use it to connect with any server to report its status. That means it's not possible to check if you can connect with the server without starting a session, unlike every other tool in this switcher.

So if you want to make sure you can connect with a new server, you need to start a session. There is a --approve-mcps option that can be useful in such scenarios, but it's not really suitable as it approves everything and it's not good to approve random servers.

In Gemini CLI

It's worth to mention that gemini mcp add comes with a --scope flag which is set to project by default — the neighbouring CLIs don't all put a bare add in the same place, so it's easy to assume wrong here. So you can define the user-level server like:

gemini mcp add wc python3 ./tools/word_count.py -e WC_LOG=/tmp/wc.log
gemini mcp add --scope user --transport http notion https://mcp.notion.com/mcp

The storage locations are different, for every scope:

• project — in mcpServers block of .gemini/settings.json file placed in the current directory

• user — in mcpServers block of ~/.gemini/settings.json file

This is what the record might look like:

{
  "mcpServers": {
    "wc": {
      "command": "python3",
      "args": ["./tools/word_count.py"],
      "env": { "WC_LOG": "/tmp/wc.log" }
    }
  }
}

There are also a few more flags you can use to alter behaviour of the server:

• --include-tools / --exclude-tools — to control what tools the server adds to the context

• --trust — to skip the confirmation prompt (for this particular server)

• gemini mcp enable / disable — to turn off and on the server without removing it

The gotcha. If you have a project that is not trusted by the Gemini CLI (eg in case of a fresh checkout), all the servers will be turned off, including user-scope ones; no matter how long time ago you created them. You can see an output like this:

Warning: MCP servers are configured but disabled because this folder is untrusted.
User-level servers are also suppressed in untrusted folders to prevent accidental side-effects.

Configured MCP servers:

○ wc: python3 ./tools/word_count.py (stdio) - Disabled

So run gemini mcp list in a new checkout before wondering where your tools went. And one naming trap if you also run Antigravity CLI: it keeps its servers in ~/.gemini/config/mcp_config.json — same directory, different file. That's from the documentation bundled in the agy binary rather than a published page, so check it against your own install before you go editing.

In Kimi Code CLI

There's no mcp subcommand in Kimi Code CLI. You define the servers in a JSON file and manage them from inside a session with /mcp-config, while /mcp shows the connection status of all of them.

You can define the configuration in two places:

• The ~/.kimi-code/mcp.json or $KIMI_CODE_HOME/mcp.json files for the user-level scope

• .kimi-code/mcp.json file under the project's working directory, where the project-level entry takes precedence over the user-level one with the same name

Here's an example:

{
  "mcpServers": {
    "wc": {
      "command": "python3",
      "args": ["./tools/word_count.py"]
    },
    "linear": {
      "url": "https://mcp.linear.app/mcp"
    }
  }
}

In order to log in to the remote server, you need to run /mcp-config login <server-name>. For timeouts, make sure to configure them separately in config.toml, not in the JSON file. Here's an example:

[mcp]
startup_timeout_ms = 30000

When using tools on the MCP servers, their names will be mcp__<server>__<tool>. This is also the name used in permission rules; you can create wildcards so a single rule could allow for the entire server. For instance, you can do it like this:

[[permission.rules]]
decision = "allow"
pattern = "mcp__wc__*"

The gotcha. A stdio entry in a project-level .kimi-code/mcp.json — the wc one above — runs python3 ./tools/word_count.py on your machine every time you open a session in that project. Given the above, Kimi Code developers recommend enabling it only in trusted repositories. This is especially important given that Kimi Code doesn't have any isolation on the OS level (there's no data under the "Sandbox" row in this Academy table), so if a server turns out to be something other than what its name suggested there's nothing that could protect you from this.