Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/neon-solutions/add-mcp/llms.txt

Use this file to discover all available pages before exploring further.

Most problems with add-mcp fall into a small number of categories: agent detection issues, shell-quoting mistakes in flag values, one-time setup steps that were skipped, or agent-specific behaviour after installation. This page covers each scenario with a direct fix.

​
Installation Issues

Symptom: The install appears to succeed (no errors, config file updated) but the MCP server is not available inside the agent.Cause: Many agents do not hot-reload their MCP configuration. They require an explicit action to pick up new servers.Fix — Claude Code: Restart Claude Code completely after installing a new server.Fix — Cursor: Open Cursor’s MCP settings page (Settings → MCP) and toggle the new server on. Cursor writes the config to .cursor/mcp.json but requires the toggle to be enabled before it connects.Fix — other agents: Check the agent’s own documentation for how to reload extensions or context providers. When in doubt, a full restart is the safest option.
Symptom: add-mcp reports that no agents were detected in the project or globally, and either exits or defaults to an empty selection.Cause (project mode): No known config files (.cursor/, .mcp.json, .vscode/, etc.) exist in the current directory.Cause (global mode): No globally-installed agent config directories were found on the system.Fix — specify the agent explicitly:
npx add-mcp https://mcp.example.com/mcp -a cursor
Fix — global mode:
npx add-mcp https://mcp.example.com/mcp -g -a claude-code
Run npx add-mcp list-agents to see all supported agents and their expected config file locations.
Symptom: add-mcp warns that one or more selected agents do not support the requested transport type (HTTP or SSE) and skips those agents.Cause: Some agents only support a subset of transports. For example, Claude Desktop only supports local stdio servers via its config file — remote HTTP/SSE servers must be added through its in-app Settings → Connectors UI.Fix — try SSE transport: If the agent supports SSE but not HTTP streamable, pass --transport sse:
npx add-mcp https://mcp.example.com/sse --transport sse -a <agent>
Fix — choose a compatible agent: Select an agent that supports the transport your server requires. Run npx add-mcp list-agents for an overview of all agents and their supported transports.

​
Flag and Format Errors

Symptom: The CLI exits with Invalid agents: <name> after you pass -a <name>.Cause: The agent name is misspelled or uses an unsupported alias.Fix: Run npx add-mcp list-agents to print the full list of valid agent identifiers and aliases:
npx add-mcp list-agents
Valid identifiers include: antigravity, cline, cline-cli, claude-code, claude-desktop, codex, cursor, gemini-cli, goose, github-copilot-cli, mcporter, opencode, vscode, windsurf, zed.Supported aliases: codeium / cascade → windsurf, cline-vscode → cline, gemini → gemini-cli, github-copilot → vscode.
Symptom: The CLI exits with an error about the --header flag format.Cause: Headers must be passed as 'Key: Value' strings. A common mistake is using double quotes with a shell variable, e.g. --header "Authorization: Bearer $TOKEN" — if $TOKEN is unset or the shell expands it to an empty string, the value becomes blank and add-mcp rejects it.Fix: Use single quotes to pass the template literally. The add-mcp interactive mode will then prompt you to fill in the value:
# Good — passes the placeholder literally
npx add-mcp https://mcp.example.com/mcp --header 'Authorization: Bearer ${TOKEN}'

# Bad — shell expands $TOKEN before add-mcp sees it
npx add-mcp https://mcp.example.com/mcp --header "Authorization: Bearer $TOKEN"
In non-interactive mode (-y), the placeholder string ${TOKEN} is written verbatim into the config file. Replace it manually afterwards if needed.
Symptom: The CLI exits with an error about the --env flag format.Cause: Environment variables must be passed as 'KEY=VALUE' strings. The same shell-expansion issue applies: using double quotes can cause the value to be empty if the variable is not set in the current shell.Fix: Use single quotes:
# Good — passes the template literally to add-mcp
npx add-mcp @org/mcp-server --env 'API_KEY=${MY_API_KEY}'

# Bad — shell expands $MY_API_KEY before add-mcp receives it
npx add-mcp @org/mcp-server --env "API_KEY=$MY_API_KEY"
add-mcp rejects --env 'KEY=' with an empty value. If your shell silently expanded a variable to an empty string, this is the likely cause.

​
Registry and Find Issues

Symptom: Running npx add-mcp find <keyword> exits immediately with guidance to rerun without --yes.Cause: The first time find or search runs, add-mcp prompts you to select which registries to enable (add-mcp curated registry and/or official Anthropic registry). If you passed -y / --yes before completing this one-time setup, the CLI cannot prompt and exits safely.Fix: Run without --yes to complete the interactive registry selection:
npx add-mcp find vercel
Your selection is saved to ~/.config/add-mcp/config.json and used for every subsequent search. After setup, you can use -y freely.Reset: To re-trigger the prompt, delete the findRegistries key from ~/.config/add-mcp/config.json (or delete the file entirely).

​
Config File Issues

Symptom: You want to know the exact path of the config file that add-mcp wrote, or you want to verify the install location before committing.Fix: Run npx add-mcp list to display all detected agents and the absolute path of each config file:
# Project-level configs in the current directory
npx add-mcp list

# Global user-level configs
npx add-mcp list -g

# Config for a specific agent (shown even if not detected)
npx add-mcp list -a cursor
Project-scope config paths (relative to your project root):
AgentProject config path
Claude Code.mcp.json
Cursor.cursor/mcp.json
VS Code.vscode/mcp.json
GitHub Copilot CLI.vscode/mcp.json
Codex.codex/config.toml
Gemini CLI.gemini/settings.json
Goose.goose/config.yaml
OpenCodeopencode.json
MCPorterconfig/mcporter.json
Zed.zed/settings.json
Symptom: add-mcp created a project-level config file (e.g. .cursor/mcp.json) and you don’t want it committed — it may contain tokens or personal settings.Fix: Use the --gitignore flag when installing. add-mcp automatically appends the generated config file path(s) to .gitignore in your project root:
npx add-mcp https://mcp.example.com/mcp -a cursor --gitignore
--gitignore only works with project-scope installs (without -g). Global config files live outside your repository and don’t need a .gitignore entry.
You can also add the path manually. For Cursor, add .cursor/mcp.json to your .gitignore. Run npx add-mcp list to find the exact relative path for each agent.

Build docs developers (and LLMs) love

Get started for freeTalk to us