Claude MCP Complete Guide: Claude Code and Desktop Setup, Config, Commands, and Best Servers

Claude MCP connects Claude Code or Claude Desktop to external tools and data through Model Context Protocol servers. In Claude Code, use claude mcp add for local stdio or remote HTTP servers, choose the correct configuration scope, run claude mcp list, and inspect /mcp before you let a server act on real data. In Claude Desktop, prefer reviewed desktop extensions or authenticated remote connectors where available.

This guide covers the current setup paths, configuration files, commands, server selection, and troubleshooting. Product-specific pages remain the canonical source for exact servers; this page explains how those servers fit into Claude.

Which Claude MCP setup should you use?

Claude supports more than one MCP experience. Pick the client and connection type before copying a command.

Goal	Use	Connection	Best setup path
Work in a terminal coding agent	Claude Code	Local stdio or remote HTTP	`claude mcp add`
Share a server definition with a repository	Claude Code project scope	Local or remote	Commit `.mcp.json` without secrets
Use local files or desktop apps in chat	Claude Desktop	Desktop extension/local server	Settings → Extensions
Connect Claude to a cloud service	Claude connectors	Remote MCP	Settings → Connectors and OAuth
Centrally govern enterprise connections	Managed Claude Code/Desktop	Managed configuration	Admin policy and allow/deny rules

Anthropic’s Claude Code MCP documentation recommends HTTP for remote servers and documents stdio for local processes. The legacy SSE transport is deprecated; use HTTP where the server offers it.

Original Graphify illustration: Claude connects to local code and files through a local process, and to cloud systems through an authenticated remote boundary.

How do you add an MCP server to Claude Code?

Use claude mcp add, place every option before the server name, and place -- before the executable for stdio servers. Then verify the saved definition and connection status.

How do you add a remote HTTP MCP server?

Use this form for a remote Streamable HTTP endpoint:

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

Example with a placeholder endpoint:

claude mcp add --transport http docs https://mcp.example.com/mcp

For an OAuth-enabled server, add it first, open Claude Code, and use /mcp to authenticate. Avoid a static bearer token when the server provides a supported OAuth flow.

How do you add a local stdio MCP server?

Use this form for a reviewed executable that Claude Code should launch:

claude mcp add --transport stdio <name> -- <command> [args...]

Example with a generic local package:

claude mcp add --transport stdio local-docs -- npx -y example-docs-mcp

The double dash matters. Claude Code options such as --transport, --env, and --scope must appear before the server name. Server command arguments belong after --.

How do you pass environment variables?

Pass secrets to the server environment instead of embedding them in a shared file:

claude mcp add --transport stdio \
  --env SERVICE_API_KEY="$SERVICE_API_KEY" \
  service -- npx -y example-service-mcp

This keeps the literal value out of .mcp.json, but it may still be stored in local Claude configuration when passed as a value. Prefer environment expansion or the server’s OAuth flow for reusable setups. Never commit an API key.

What are the Claude MCP commands?

The core Claude MCP list command and management commands are:

claude mcp list

claude mcp get <name>

claude mcp remove <name>

claude mcp add-json <name> '<json>'

claude mcp add-from-claude-desktop

claude mcp reset-project-choices

claude mcp serve

Inside Claude Code, use:

/mcp

The /mcp panel shows connection status and available tool counts. It also starts OAuth login for supported remote servers. Treat claude mcp list as configuration evidence and /mcp as live-session evidence; you need both when debugging.

Which Claude Code MCP configuration scope should you choose?

Claude Code supports local, project, and user scopes. The scope controls where a server loads, who receives the definition, and where it is stored.

Scope	Loads in	Shared with team	Stored in	Best use
local (default)	Current project	No	Project entry inside `~/.claude.json`	Experiments, personal credentials, one repository
project	Current project	Yes	`.mcp.json` in the repository root	Reviewed team configuration
user	All projects	No	`~/.claude.json`	Trusted personal utilities used everywhere

Add the --scope option before the name:

claude mcp add --transport http --scope project docs https://mcp.example.com/mcp

For the same server name, Claude Code uses this precedence: local, project, user, plugin-provided, then Claude connectors. A higher-precedence duplicate can make a correct lower-level definition appear ignored.

Claude MCP local, project, and user configuration scopes

Original Graphify illustration: nested configuration scopes converge on one active definition when names or endpoints overlap.

What does `.mcp.json` do in Claude Code?

.mcp.json stores project-scoped MCP server definitions that a team can review and share through version control. Claude Code asks for approval before using a project-scoped server from this file.

A remote example:

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "${DOCS_MCP_URL:-https://mcp.example.com/mcp}",
      "headers": {
        "Authorization": "Bearer ${DOCS_MCP_TOKEN}"
      }
    }
  }
}

A local example:

{
  "mcpServers": {
    "repo-helper": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "example-repo-mcp"],
      "env": {
        "REPOSITORY_ROOT": "${CLAUDE_PROJECT_DIR:-.}"
      }
    }
  }
}

Claude Code expands ${VAR} and ${VAR:-default} in command, arguments, environment, URL, and headers. If a required variable has no value or default, parsing fails. Commit variable names and safe defaults—not secret values.

What does `claude --mcp-config` do?

The search phrases claude --mcp-config and claude code --mcp-config refer to starting Claude Code with an explicit MCP configuration file. Use it for an isolated configuration or automation that should not depend on the normal saved scopes.

claude --mcp-config ./path/to/mcp-config.json

Check your installed Claude Code version’s claude --help output before scripting this flag. CLI surface area can change faster than third-party tutorials.

How do you set up MCP in Claude Desktop?

For current Claude Desktop releases, Anthropic presents two primary paths:

How do you install a local desktop extension?

Open Settings → Extensions.
Browse the extension directory.
Install a reviewed extension.
Configure required values in the extension interface.
Restart or inspect extension logs if tools do not appear.

Anthropic’s local MCP server guide explains Desktop Extensions (.dxt) and organization controls. A DXT package reduces manual JSON and dependency work, but you should still review its publisher and requested access.

How do you add a remote connector?

Open Settings → Connectors.
Choose a pre-built connector or Add custom connector.
Use the URL published on the provider’s official site.
Authenticate and review OAuth permissions.
Enable only the tools needed for the task.

Remote connectors are appropriate for cloud services. Local desktop extensions are appropriate when the server must reach files or applications on your computer. Anthropic’s comparison of desktop and web connectors recommends matching the connection type to the data boundary.

What about `claude_desktop_config.json` and stdio?

Some local servers still document a manual Claude Desktop configuration. Follow the server’s current official instructions and use an absolute executable path if the desktop application cannot resolve your shell PATH. Prefer the extension UI when the same integration ships as a reviewed DXT.

Do not copy a random claude_desktop_config.json block without checking the package name, command, arguments, environment, and publisher. A JSON configuration is executable setup, not inert documentation.

What are the best MCP servers for Claude?

The best Claude MCP servers cover distinct jobs with little overlap. Start with two or three read-oriented capabilities.

Need	Recommended starting point	Canonical Graphify profile	Claude-specific note
Current library docs	Context7	Context7 MCP	Add project-specific usage instructions rather than loading every library
Code navigation and memory	Serena or Graphify	Serena	Scope indexing to the intended repository
Source control	GitHub	GitHub MCP Server	Start read-only; protect merge and write actions
Browser testing	Playwright	Playwright MCP	Use a separate test profile and non-production account
Database work	Supabase or Postgres	Supabase MCP, Postgres MCP	Use a read-only database role for exploration
Project planning	Atlassian	Atlassian MCP	Separate search from issue creation/editing
Knowledge and notes	Notion	Notion MCP	Confirm workspace and page access
Workflow automation	n8n	n8n MCP	Review downstream side effects before execution
Cloud documentation	AWS Docs	AWS Docs MCP	Keep documentation access separate from infrastructure control

How do Context7 and Claude Code work together?

Queries such as Claude Code MCP Context7 and Context7 MCP Claude Code belong to the dedicated Context7 profile. The integration pattern is simple: Claude calls a documentation tool with a library identity and version, then uses the returned official documentation while coding.

The benefit is freshness and version targeting. The risk is context volume and misplaced trust. Ask for the narrow documentation slice you need and retain links or identifiers that let you verify it.

How do Serena and Claude Code work together?

Queries such as Claude Code Serena, Serena MCP Claude Code, Serena Claude, and Serena Claude Code belong to the Serena profile. Serena focuses on semantic code navigation and editing workflows. Review its repository scope and edit capabilities before enabling it across projects.

Graphify covers a complementary need: it turns code, documents, and design artifacts into a living knowledge graph. Use this structural context when Claude needs to reason across modules rather than retrieve isolated files.

How do you add Supabase, Postgres, or MySQL?

Use the provider’s current endpoint or package instructions, then apply least privilege:

Claude Code add MCP Supabase: begin with the Supabase MCP profile and a restricted project role.
Claude MCP Postgres / Claude Postgres MCP: use the Postgres MCP profile and a read-only connection for inspection.
Claude MySQL MCP / Claude Snowflake MCP / Snowflake MCP Claude: separate schema and query access from mutation or administrative operations.

Never give a general coding session a production owner credential.

How do you add Playwright or Puppeteer?

For add Playwright MCP to Claude Code, install Playwright MCP Claude Code, and Claude Playwright MCP, follow the Playwright MCP profile. Use a test account, isolate browser state, and confirm before submissions, purchases, or destructive actions.

For Claude Code Puppeteer MCP or Puppeteer MCP Claude Code, verify the package and publisher because similarly named community servers exist. Do not run browser automation against a personal profile that contains unrelated authenticated sessions.

How do you add GitHub, Atlassian, Jira, or Notion?

For Claude Code GitHub MCP and add GitHub MCP to Claude Code, use the GitHub MCP profile. Start with repository read access.
For Atlassian MCP Claude Code and add Atlassian MCP to Claude Code, use the Atlassian MCP profile and review site scopes.
For Jira MCP Server Claude Code, route through the Atlassian/Jira product documentation and separate search from issue mutation.
For Claude MCP Notion, use the Notion MCP profile and restrict page access.

What about memory, filesystem, and other specialized servers?

Use Claude memory MCP or Claude Code memory MCP only after you understand retention, deletion, and cross-project isolation. Use Claude filesystem MCP with explicit allowed roots. A filesystem server should not receive your entire home directory by default.

Specialized searches—including Claude MCP SSH, Claude Outlook MCP, Claude MCP PDF, Claude Projects MCP, Claude Code Stripe MCP, Vercel MCP Claude Code, Excalidraw MCP Claude Code, Unity MCP Claude, Claude Mac MCP RStudio, Sequential Thinking MCP Claude Code, Windows-MCP Claude, Claude Python MCP, and browser MCP Claude—represent separate trust and capability profiles. Verify each publisher and keep the exact product page canonical rather than relying on a generic list.

How do you verify a Claude MCP installation?

Use this sequence after every change:

Run claude mcp get <name> and confirm the saved type, command or URL, and scope.
Run claude mcp list and check whether the server connects.
Open Claude Code and run /mcp.
Inspect the live tool count and authenticate if required.
Ask Claude to describe the available tools without calling them.
Run one read-only operation with test data.
Review the returned source, server logs, and permission prompt.
Test one expected failure, such as an out-of-scope path or unauthorized write.

A successful connection proves transport and initialization. It does not prove that the right server is running or that every tool is safe.

Why is Claude MCP not working?

Diagnose the first failed layer instead of reinstalling everything.

Symptom	Likely cause	Check	Fix
Server not listed	Wrong scope or configuration not parsed	`claude mcp list`, JSON syntax, current directory	Re-add in the intended scope; fix missing environment variables
`spawn ... ENOENT`	Executable not in the app’s PATH	`which <command>`	Use an absolute path or install the runtime
Server disconnects at startup	Package crash, missing argument, or bad environment	Server stderr/logs	Run the command directly and resolve its first error
Authentication required	OAuth flow not completed	`/mcp`	Authenticate, then retry
Tools are missing	Capability mismatch, delayed connection, or server exposes no tools	`/mcp` tool count	Wait, update, or inspect the server’s advertised capabilities
Project server ignored	Duplicate name at a higher-precedence scope	`claude mcp get`, local/user config	Remove or rename the duplicate
`.mcp.json` fails	Undefined `${VAR}` without a default	Shell environment and JSON	Set the variable or add a safe default
Huge context or slow selection	Too many servers/tools or large tool output	`/mcp`, response size	Disable unused servers; narrow tools and outputs
Desktop extension has no tools	Extension config or refresh issue	Settings → Extensions → logs	Review settings and restart Claude Desktop

Claude Code warns when a tool output exceeds 10,000 tokens and uses a default maximum of 25,000 tokens for tools without their own limit, according to the current official documentation. Use MAX_MCP_OUTPUT_TOKENS only after fixing unnecessarily broad queries.

Why does stdio connect in a terminal but fail in Claude Desktop?

Desktop applications often inherit a different environment from your interactive shell. Use an absolute executable path, provide required environment variables explicitly, and inspect the extension or server logs. Do not solve PATH errors by running the whole desktop app with excessive privileges.

Why does a server show zero tools?

The server may expose only resources or prompts, may require authentication before publishing tools, or may have declared the tools capability without returning tools. Inspect /mcp, server logs, and the server’s official capability documentation.

How do you secure Claude MCP?

Apply controls at several layers:

Choose provenance: install from the provider’s official page or a verified registry record.
Minimize scope: prefer local or project scope over user scope for task-specific tools.
Protect secrets: use OAuth or environment expansion; never commit tokens.
Separate read and write: use different credentials or server profiles where possible.
Constrain local access: allow specific directories, not an entire home folder.
Review live tools: a package name does not tell you every action it exposes.
Require confirmation: protect destructive, publishing, financial, and external-message actions.
Isolate browser state: use test accounts and dedicated profiles.
Log and revoke: keep enough evidence to investigate and remove access quickly.
Treat external content as untrusted: files, issues, pages, and tool results can contain prompt-injection attempts.

For teams, Claude Code supports managed MCP configuration and allow/deny policies. A deny rule takes precedence over an allow rule. Central policy reduces configuration drift but does not replace server-side authorization.

Frequently asked questions

What is Claude MCP?

Claude MCP is Claude’s use of Model Context Protocol to connect to external servers that expose tools, resources, or prompts. Claude Code, Claude Desktop extensions, and remote connectors use different configuration experiences.

Is Claude an MCP client?

Claude Code and Claude Desktop act as MCP hosts and manage client connections to servers. The underlying Claude model is not itself the network client.

Where is Claude Code MCP configuration stored?

Local and user scopes are stored in ~/.claude.json. Project-scoped servers are stored in .mcp.json at the repository root.

What is the Claude MCP server config format?

Each entry sits under mcpServers and defines a local stdio command or a remote URL. Use claude mcp add to generate the correct shape when possible.

How do I list Claude MCP servers?

Run claude mcp list in the terminal. Inside Claude Code, run /mcp to inspect live status, tools, and authentication.

Can Claude Code itself run as an MCP server?

Yes. Run claude mcp serve to expose Claude Code’s tools over stdio to another MCP client. The consuming client remains responsible for user confirmation and safety controls.

Are Claude Desktop MCP servers the same as Claude Code servers?

They can point to the same server, but configuration, packaging, scope, and supported features differ. Claude Code can import selected Desktop servers on macOS and WSL with claude mcp add-from-claude-desktop.

Which Claude MCP servers should I install first?

Install one server for your highest-value recurring job and one for supporting context. A documentation server plus a repository or code-understanding server is a strong read-oriented starting point.

Recommended Claude MCP rollout

Start in a disposable repository. Add one server at local scope. Inspect its live tools. Complete a read-only task. Record permissions and data flow. Move the definition to project scope only after review, and keep secrets in environment variables or OAuth storage. Add a second server only when it closes a measured capability gap.

For current product instructions, use the dedicated MCP server directory and exact product profiles linked above. For protocol concepts, read What Is MCP?.