How to add an MCP server to Claude Code safely

To add an MCP server to Claude Code safely, inspect the server first, choose remote HTTP or local stdio, install it at the narrowest useful scope, keep secrets out of shared configuration, confirm the server's status and tool list, and run a read-only test before granting write access.

Claude Code makes the connection step short. The security work is deciding what the new server can read and change—and who will inherit that configuration.

Before you connect anything

Collect four pieces of information from the server's official documentation:

1. Publisher and source: repository, package, release, and maintenance history.
2. Transport: an HTTPS MCP endpoint or a local launch command.
3. Authentication: OAuth, an API token, environment variables, or no credential.
4. Capability: the tools, resources, and prompts the server exposes, including writes.

Do not copy a configuration block from an issue comment or random gist without tracing it back to the publisher. A local stdio command runs software on your machine. A remote server receives requests and potentially your work data. Both are trust decisions.

If MCP terminology is new, read what an MCP server is before installing one. If the job only needs reusable instructions, an agent skill may be simpler.

Choose remote HTTP or local stdio

Use HTTP when the provider gives you an https://.../mcp endpoint. Claude Code's current documentation recommends HTTP for remote services because it is the broadly supported cloud transport and supports OAuth flows.

Use stdio when the provider gives you a command such as an executable, npx, or uvx. Claude Code launches that process locally and exchanges MCP messages over its standard input and output.

Use legacy SSE only when the server still exposes an SSE endpoint and no HTTP option. Claude Code marks SSE as deprecated. WebSocket configurations also exist for servers that push unsolicited events, but they require JSON configuration and do not use the standard --transport installation flag. For an ordinary request-response integration, prefer HTTP.

Add a remote HTTP server

The current command shape is:

claude mcp add --transport http <name> <url>

LLM Mart's public catalogue is a useful zero-secret example:

claude mcp add --transport http llmmart https://llmmart.ai/mcp

The command adds the server at local scope by default, meaning it is available only to you in the current project. It writes the definition under that project's entry in ~/.claude.json.

For a server that uses OAuth, add the endpoint first, start Claude Code, run /mcp, and follow the browser sign-in flow. Prefer OAuth or a provider-supported credential flow over pasting a long-lived token into shell history.

If a server genuinely requires a static header, do not hard-code the value in a shared .mcp.json. Use environment expansion in configuration or a supported credential helper, and confirm the provider's exact header format.

Add a local stdio server

For a local command, put Claude Code options before -- and the server command after it:

claude mcp add <name> -- <command> [arguments...]

A filesystem server illustrates why arguments matter:

claude mcp add project-files --scope local -- \
  npx -y @modelcontextprotocol/server-filesystem /absolute/path/to/project

The final path is the server's allowed root. Replace it with one specific project directory; do not point the first test at your home folder or filesystem root. Review the package and version policy before letting npx download or run it. Where reproducibility matters, pin an approved version rather than floating to the newest release.

Pass required environment values with configuration designed for the server. Avoid putting secret values directly in a command that will be saved in shell history or copied into documentation.

Pick the correct scope

Claude Code supports three user-configurable MCP scopes:

Use local for experiments, personal credentials, and project-specific servers you do not want to commit. It is the safest default for a first connection.

Use project when the server definition belongs to the team and contains no secrets. Claude Code stores it in .mcp.json, which can be reviewed and versioned. Interactive sessions prompt before using a project-scoped server for the first time.

Use user for a personal utility you genuinely need across projects. Be careful: a broadly capable user-scoped server follows you into repositories that may contain unrelated sensitive data.

Share .mcp.json without sharing secrets

A project configuration can use environment-variable expansion:

{
  "mcpServers": {
    "team-api": {
      "type": "http",
      "url": "${TEAM_API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${TEAM_API_TOKEN}"
      }
    }
  }
}

Commit the variable names and non-sensitive endpoint. Keep each developer's token in their secret manager or local environment. Note the failure mode: if a referenced variable is unset and has no default, Claude Code still loads the configuration, uses the unexpanded ${VAR} text as-is, and only reports a missing-variable warning for that server in claude mcp list output. The server fails to authenticate rather than refusing to start, so read that warning instead of treating a clean add as a working credential.

Before committing .mcp.json, review the diff for embedded tokens, private hostnames, excessive filesystem roots, shell commands, and unexpected packages. Treat a changed server command or URL as an executable dependency update.

Verify configuration and connection separately

Use the management commands:

claude mcp list
claude mcp get llmmart

Inside Claude Code, run:

/mcp

An “Added” message means the configuration was written. It does not prove the endpoint is reachable, authentication succeeded, or the tools are safe. claude mcp list reports connection or approval status; claude mcp get <name> shows the resolved definition; /mcp lets you inspect and manage the server in the session.

Then inspect the tools actually exposed. Compare their names, descriptions, and input schemas with the provider's documentation. A server claiming read-only behavior should not quietly offer delete, publish, send, or arbitrary-execution tools.

Run a low-risk first test

For LLM Mart, ask Claude to search the public catalogue for a code-review skill and return only titles and listing links. Do not ask it to install or execute the returned skill. LLM Mart explicitly labels catalogue bodies as community-authored, untrusted text.

For a local filesystem server, create a temporary test directory with two synthetic files. Confirm that the server can read the allowed file and cannot reach a sibling directory. If it exposes writes, keep them disabled or require approval until the read boundary is proven.

Record:

• the server revision or package version;
• transport and scope;
• tools exposed;
• files, domains, and accounts reachable;
• authentication scopes;
• calls attempted and completed; and
• any human approvals.

The first successful response is not the end of the test. Confirm the server stayed within its stated boundary.

Troubleshoot common failures

The server was added but does not connect. Run claude mcp list and claude mcp get <name>. Check the URL, transport type, local executable, arguments, and required environment variables. A URL entry without a type is invalid because Claude Code interprets a missing type as stdio.

Authentication is required. Open Claude Code, run /mcp, and complete the OAuth flow. For a pre-configured OAuth client, verify the client ID, registered callback URI, and callback port against the provider documentation.

A local server fails to spawn. Run the underlying command yourself only after reviewing it. Check that the executable exists, the package can be resolved, and every configured path is absolute and permitted.

A project server is pending approval. Start an interactive session, inspect the .mcp.json definition, and approve it from the MCP interface only if it matches the reviewed change.

The server connects but exposes zero tools. It may provide only resources or prompts, your credentials may lack scopes, or the client and server may disagree on capabilities or protocol era. Inspect the server's advertised features rather than assuming every MCP server has tools.

The name already exists. Choose whether to update or remove the existing definition. Local, project, user, plugin, and connector sources have precedence rules; duplicate names can make a different configuration win than the one you edited.

Remove the server and revoke access

Remove a configured server with:

claude mcp remove <name>

Specify the same scope used during installation if needed. Removing a definition stops Claude Code from loading it, but complete the offboarding at the source service too: revoke tokens or OAuth grants, remove temporary credentials, and check for server-side sessions or retained data. Claude Code's documentation says removing a remote server also deletes the OAuth tokens and client registration it stored for that server; revoking at the provider remains the stronger independent check.

Finally, rerun claude mcp list and confirm the server is gone. If the configuration was committed, review and merge the .mcp.json removal so teammates do not reconnect it later.

Next step: Connect Claude Code to LLM Mart's read-only public MCP endpoint, inspect the exposed catalogue tools, and run a title-and-link search before adding any server with write authority.

Sources

• Claude Code: connect to tools via MCP
• Model Context Protocol 2026-07-28: transports
• Model Context Protocol: example servers
• LLM Mart: API and MCP server