Setup · about 10 minutes

Connecting an MCP server to Claude

Two paths. Hosted servers are a few clicks in the Claude interface. Local servers need one JSON file. Neither needs an engineer, though the second assumes you are comfortable saving a file in a folder you have not visited before.

Working in the Claude app rather than a terminal? Most reps are. That flow has no config files and takes about five minutes: connecting a server in Claude on web or desktop. This page is for Claude Code and local servers.

Path A: a hosted server

Open connector settings

In Claude Desktop or claude.ai, go to Settings, then Connectors. Choose Add custom connector and paste the server URL. Hosted servers use streamable HTTP, so the URL usually ends in /mcp.

Authorise with the narrowest scope

Most hosted servers use OAuth. If the consent screen offers read and write, take read for the first week. For key-based servers, paste the key when prompted. Keys belong to a person and inherit that person's permissions, so issue a service account rather than using an admin login.

Confirm the tools loaded

Open a new chat and check the tools indicator. You should see the server name with its tool count. If the count is zero the handshake succeeded but the tool list did not, which usually means the token lacks scope.

Path B: a local server

Local servers run on your machine over stdio. Claude launches the process itself, so the config tells it what command to run.

Edit claude_desktop_config.json. On macOS it lives at ~/Library/Application Support/Claude/, on Windows at %APPDATA%\Claude\. If the file does not exist, create it.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Documents/accounts"
      ]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://readonly:pw@replica.internal:5432/app"
      }
    },
    "salesgear": {
      "command": "npx",
      "args": ["-y", "salesgear-mcp"],
      "env": { "SALESGEAR_API_KEY": "sk_live_..." }
    }
  }
}

Restart Claude Desktop completely. The config is read at launch, not on save, and a window reload is not enough.

Claude Code

The CLI takes the same servers without hand-editing JSON:

# hosted, streamable HTTP
claude mcp add --transport http salesgear https://mcp.example.com/mcp \
  --header "Authorization: Bearer sk_live_..."

# local, stdio
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres

# check what is attached
claude mcp list

Verify with a read-only prompt

Do not start with something that writes. Run a question whose answer you already know, so a wrong answer is obvious:

Using the CRM tools, list the five open opportunities
with the largest amount, and for each one give the stage
and the date of the most recent logged activity.
Do not guess. If a field is empty, say it is empty.

Two failure modes to watch. If Claude answers without calling a tool, it is inventing the list, and the tool description is not matching the request. If it calls the tool and returns nothing, the credential is scoped too tightly.

The rule worth keeping: the model gets the same access as the person running it, never more. An account executive's connector should not reach territory data the account executive cannot open in the CRM interface. The permissions model and the rollout order are covered in Salesgear's guide to MCP for sales teams.

When a tool never fires

Symptom	Usual cause	Fix
Server missing from the tools list	Config JSON is invalid or Claude was not fully restarted	Validate the JSON, quit the app from the menu bar, relaunch
Server listed, zero tools	Handshake succeeded, token has no scope	Reissue the credential with the required read scopes
Model answers without calling the tool	Prompt does not resemble the tool description	Name the tool in the prompt once, then generalise
Tool called, empty result	Filter mismatch, often a field name that does not exist	Ask the model to print the exact arguments it sent
Works alone, not with others attached	Too many tools, model picks the wrong one	Detach servers you are not using in that session
Local server exits at launch	Node version too old for the package	Point `command` at an absolute path to a current Node

Once a server is attached and answering, the useful next step is a workflow you run every day rather than a demo. There are eight on the workflows page, and a role-by-role view of where they fit, from SDR through VP, in this guide to using Claude for sales.

Workflows Server directory

Config paths and CLI flags checked against Claude Desktop and Claude Code as of July 2026.