Connect Claude Code to Remote MCP Servers

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Problem

You want to connect Claude Code to a cloud-hosted MCP server (like Notion, Asana, or a custom API) but the connection fails, authentication does not work, or the server shows as disconnected in /mcp.

Quick Fix

Add a remote HTTP MCP server with authentication:

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

For servers requiring a Bearer token:

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

What’s Happening

MCP servers can run locally (stdio transport) or remotely (HTTP or SSE transport). Remote servers are the recommended option for cloud-based services because they do not require local process management. HTTP is the preferred transport; SSE (Server-Sent Events) is deprecated but still supported for older servers.

Remote servers often require authentication via Bearer tokens, API keys, or OAuth 2.0. Claude Code passes configured headers with every request. For OAuth servers, Claude Code handles the authentication flow when you use /mcp to connect.

Step-by-Step Fix

Step 1: Add an HTTP server

HTTP is the recommended transport for remote MCP servers:

claude mcp add --transport http my-service https://api.example.com/mcp

Step 2: Add authentication headers

Pass authentication with --header flags:

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

# API key header
claude mcp add --transport http my-api https://api.example.com/mcp \
  --header "X-API-Key: your-key-here"

Step 3: Use OAuth authentication

Some remote servers use OAuth 2.0. After adding the server, authenticate through the /mcp command inside Claude Code:

/mcp

Select the server and follow the OAuth flow. Claude Code handles token exchange and refresh automatically.

Step 4: Add an SSE server (legacy)

For older servers that only support SSE:

claude mcp add --transport sse asana https://mcp.asana.com/sse

# With authentication
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Note: SSE transport is deprecated. Use HTTP transport when available.

Step 5: Choose the right scope

Control where the server configuration is stored:

# Local: only you, only this project (default)
claude mcp add --transport http --scope local my-api https://api.example.com/mcp

# Project: shared with team via .mcp.json
claude mcp add --transport http --scope project my-api https://api.example.com/mcp

# User: available across all your projects
claude mcp add --transport http --scope user my-api https://api.example.com/mcp

Project scope stores the configuration in .mcp.json at the project root, which can be committed to version control. Do not commit files containing secret tokens; use environment variable interpolation instead.

Step 6: Verify the connection

Check server status:

claude mcp list
claude mcp get my-api

Inside Claude Code:

/mcp

The server should show a green status. If it shows red, check:

Step 7: Troubleshoot connection failures

If the server shows as disconnected:

  1. Test the URL directly: 
    curl -I https://api.example.com/mcp
  2. Check if your network blocks the server: 
    curl -v https://api.example.com/mcp 2>&1 | head -20
  3. Verify authentication works: 
    curl -H "Authorization: Bearer your-token" https://api.example.com/mcp
  4. If behind a corporate proxy, ensure proxy environment variables are set in your Claude Code settings.

Step 8: Remove or update servers

# Remove a server
claude mcp remove my-api

# To update, remove and re-add with new configuration
claude mcp remove my-api
claude mcp add --transport http my-api https://new-url.example.com/mcp

Prevention

Use HTTP transport for all new MCP server connections. Store shared server configurations at project scope in .mcp.json for team consistency. Keep authentication tokens in environment variables and reference them with --env flags rather than hardcoding them in configuration files.

Periodically check server status with /mcp to catch configuration drift or expired tokens.

Level Up Your Claude Code Workflow

The developers who get the most out of Claude Code aren’t just fixing errors — they’re running multi-agent pipelines, using battle-tested CLAUDE.md templates, and shipping with production-grade operating principles.

Get Claude Code Mastery — included in Zovo Lifetime →

16 CLAUDE.md templates · 80+ prompts · orchestration configs · workflow playbooks. $99 once, free forever.