Adding a Custom Connector to Claude Code — Complete MCP Setup Guide

If you want to connect Claude Code to an external tool but aren't sure where to begin, this guide is your starting point. Using MCP — Model Context Protocol, an open standard for connecting AI to external tools — Claude Code can access services like Notion, GitHub, or PostgreSQL directly, without you having to copy and paste data manually. By the end of this guide, you'll have connected at least one remote server to Claude Code and confirmed it works. Expect to spend about 10–15 minutes.

What You Need Before Starting

Check these items before you run any commands.

• Claude Code installed — Open a terminal and run claude --version. If a version number appears, you're good. If not, follow the official installation guide first.
• The server's URL or run command — For example, to connect to Notion's MCP server you need the address https://mcp.notion.com/mcp. Find this in the documentation of the service you want to connect.
• An auth token, if required — Some services need an API key or Bearer token. Generate one from that service's account settings page before you proceed.

Quick Glossary

• MCP — Model Context Protocol. An open standard that lets Claude talk to external tools. Think of it as a shared language both sides agree to use.
• MCP server — A small program that acts as a translator between Claude Code and an external service. You can use a pre-built one or create your own.
• stdio — Standard Input/Output. The communication method used by local MCP servers that run entirely on your own computer.
• HTTP server — An MCP server you reach via a URL on the internet. It's the most widely supported transport and the recommended starting point.
• SSE — Server-Sent Events. A method where the server pushes data to you in real time. Some older services use this instead of HTTP.
• Scope — A setting that controls where a connected MCP server is available: just your current project, your whole computer, or shared with your team.
• Bearer token — An authentication key that proves your identity to a service. Treat it like a password and keep it private.

Option 1: Add a Remote HTTP Server (Recommended)

According to the official Claude Code documentation, remote HTTP is the most widely supported transport for cloud-based services. Use this method when the service you want to connect already provides an MCP server URL.

1. Open a terminal and run the following command. Replace <name> with a short nickname you choose (letters only), and <url> with the server address.

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

   For example, to connect to Notion:

   claude mcp add --transport http notion https://mcp.notion.com/mcp

2. If the service requires a token, add it with the --header flag:

   claude mcp add --transport http secure-api https://api.example.com/mcp \
     --header "Authorization: Bearer your-token-here"

3. You'll know it worked when the terminal prints a confirmation message such as "Added MCP server" along with the name you chose. Start a new Claude Code session — the connected tool will be available immediately.

Option 2: Add a Remote SSE Server

Only use this option if the service's documentation explicitly mentions SSE. The syntax is the same as HTTP, just with a different transport flag.

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

Option 3: Add a Local stdio Server

Use this when the MCP server runs on your own machine — for example, a server you built yourself or one that doesn't need an internet connection.

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

For example, to connect a Node.js script called my-server.js:

claude mcp add my-server node /path/to/my-server.js

Understanding Scope — Choosing Where Your Server Works

When you add an MCP server, you can include --scope to control where it's available. If you leave it out, local is used by default — meaning the server only works in the current project folder, for you alone.

• local (default) — Works only in the current project folder, for you. Settings are saved in .mcp.json. Best for anything that contains a personal token or secret.
• project — Works in the current project folder for your whole team. The .mcp.json file gets committed to your git repository so teammates can use the same server. Important: never put tokens or passwords directly in this file, since anyone with repository access can read it.
• user — Works across all your projects on this machine. Useful for personal tools you want available everywhere without reconfiguring each project.

Here are examples with scope specified:

# Add for the whole team in the current project
claude mcp add --transport http --scope project notion https://mcp.notion.com/mcp

# Add for all your projects on this machine
claude mcp add --transport http --scope user my-tool https://my-tool.example.com/mcp

Viewing and Removing Servers

To see all servers currently registered:

claude mcp list

To remove a server by name:

claude mcp remove <server-name>

When claude mcp list shows the server name you just added, with a connected or active status, registration was successful.

Common Problems and How to Fix Them

• "claude: command not found"
  Claude Code isn't installed, or the terminal can't find it. Install Claude Code first, then open a fresh terminal window and try again.
• Server registered but tools don't appear in Claude Code
  After adding a server, you need to fully close and restart your Claude Code session. Changes aren't picked up by sessions that are already running.
• Authentication error (401 Unauthorized)
  Your Bearer token is wrong or expired. Generate a new one from the service's account settings and re-register the server with the updated --header value.
• ⚠️ Only connect servers you trust. Because MCP servers can fetch content from external sources, a maliciously crafted server could expose you to prompt injection — where hidden instructions cause Claude to take unintended actions. Start with servers listed in the Anthropic connector directory, which have been reviewed before listing.
• Accidentally committed a token to git
  If your .mcp.json ends up in a git commit with a token inside, treat that token as compromised and revoke it immediately from the service's dashboard. Going forward, use environment variables for secrets or stick to local scope.

Adding Servers via JSON Configuration

If you prefer editing files directly — or need to add several servers at once — you can edit .mcp.json by hand. The basic structure looks like this:

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

According to the official documentation, streamable-http is accepted as an alias for http in the type field — both work identically.

What to Try Next

Once a connector is live, you can ask Claude Code things like:

• "Implement the feature described in JIRA issue ENG-4521 and open a pull request on GitHub."
• "Find the emails of 10 random users who used this feature, based on our PostgreSQL database."
• "Update our email template to match the new Figma designs posted in Slack."

For a curated list of services you can connect, visit the Anthropic connector directory. Servers listed there have gone through a review process, making them a safe starting point. If you want to build your own MCP server, run /plugin install mcp-server-dev@claude-plugins-official inside a Claude Code session to install the official scaffolding plugin.