Local vs. Remote: Why Your AI Agent Can’t Find Your MCP Server

You’ve built your first Model Context Protocol (MCP) server. You run it locally, and your terminal-based AI agent, like Cline, connects to it flawlessly. It sees your tools, reads your resources, and works exactly as expected.

Then, you try to connect it to a web-based client like Claude Code, or even a sophisticated desktop tool like VS Code with Copilot, and… nothing. The client can’t find the server, or it errors out. If one client can see it, why can’t the other?

This isn’t a bug; it’s a fundamental architectural distinction that can be a major point of confusion for developers. It all comes down to one thing: where is your client really running?

The Core of the Confusion: Location, Location, Location

The heart of the issue lies in understanding where your MCP client and server are physically located and how they are allowed to communicate.

• Local Clients (like Cline or a custom script) run directly on your computer. They live in the same environment as your locally running server.
• Remote Clients (like the claude.ai/code website) run on a company’s servers, somewhere out on the internet.
• Hybrid Clients (like VS Code + Copilot) have a local component (the editor and extension) but their “brain” (the LLM agent) runs remotely in the cloud.

A local client can talk to a local server easily, like two people in the same room. A remote client trying to talk to your local server is like someone in another country trying to have a conversation with someone in a room with no phone or internet connection.

A Tale of Three Clients: Why One Connects and Others Don’t

Let’s walk through a common developer experience. A developer starts their custom MCP server with a simple Python script using the stdio transport, which is designed for local inter-process communication.

python scripts/my_mcp_server.py &

This server is designed to provide context from a local documentation file.

1. Cline (Local Terminal Agent)

The developer uses Cline, a terminal-based agent.

• Result: Success. Cline is a local application. It can launch the Python script as a child process and “talk” to it directly using stdio. The connection is seamless.

2. Claude Code (Remote Web Client)

Next, the developer tries to connect the same stdio server to the claude.ai/code website.

• Result: Failure. The Claude Code website runs on Anthropic’s remote servers. For security reasons, a website you visit in your browser has no ability to launch processes or access localhost on your machine. The connection is impossible.

3. VS Code + Copilot (Hybrid Client)

Finally, the developer configures the server in their VS Code mcp.json.

• Result: Failure. This is the most confusing case. Even though VS Code is a local application, the AI agent logic for Copilot runs on Microsoft’s remote servers. When the remote AI brain decides to call a tool, it sends a command back to the VS Code extension. However, that command - originating from the cloud - is fundamentally blocked by security boundaries from accessing your localhost. A remote server cannot initiate a connection to your private, local machine.

The Exception that Proves the Rule: Claude Desktop

“But wait,” you might say, “Claude Desktop is an official app, and it works with my local server!” This is a key piece of the puzzle.

Claude Desktop is a true local client host.

Unlike VS Code’s Copilot integration, the entire Claude Desktop application is designed to run locally. When you configure a server in its claude_desktop_config.json, the application itself is launching and managing your server process on your machine. It acts as a local orchestrator.

The “Who Can Connect?” Decision Table

This table summarizes the connection logic. The critical factor is the transport your server uses and the location of the client.

Client	Client Type	Access Local stdio?	Access localhost HTTP?	Must Use Remote HTTP Server?
Cline	Local	✅	✅	❌
Claude Desktop	Local	✅	✅	❌
VS Code + Copilot	Hybrid	❌	❌	✅
Claude Code (Web)	Remote	❌	❌	✅

Why the difference?

• Local Clients (Cline, Claude Desktop) are in the same “room” as your local server. They can see and talk to it directly.

  • Hybrid/Remote Clients (VS Code Copilot, Claude Code) have their “brain” in the cloud. For them to connect, your server must be publicly available on the internet, just like any other website or API.

The Solution: Match Your Transport to Your Client

To solve connection issues, you must configure your server’s transport to match the client you want to support.

If your client is…	Your server must use…	And your server must be…
Local (e.g., Cline, Claude Desktop)	stdio (recommended) or Streamable HTTP	Running on localhost.
Remote or Hybrid (e.g., Claude Code, VS Code + Copilot)	Streamable HTTP	Hosted on a publicly accessible URL and secured with authentication.

How to Configure Your Server for a Remote Client

If you want a remote client like Claude Code to connect to your server, you need to:

• Switch to a Network-Based Transport: Modify your server to use Streamable HTTP. The MCP SDKs for Python and TypeScript both provide easy ways to do this.

  • Expose Your Server to the Internet: A server running on localhost is only visible to your machine. You must deploy it to a cloud provider (like Cloudflare, Vercel, or AWS) or use a tunneling service like ngrok for testing.

  • Implement Robust Security: This is non-negotiable. A public server must be protected. This means implementing the MCP Authorization specification, which typically involves an OAuth 2.1 flow.

This is why many official MCP integrations (like those for Sentry or Linear) are offered by the vendors themselves - they handle the hosting, security, and maintenance of the remote server for you.

• For local development and clients like Cline or Claude Desktop:

  • Use the stdio transport. It’s simple, fast, and secure for local use.

    • No network exposure is needed.

  • For remote or hybrid clients like Claude Code or VS Code Copilot:

  • Your server must use the Streamable HTTP transport.

    • It must be deployed to a publicly accessible URL (e.g., a cloud service).

    • It must be secured with authentication (like OAuth 2.1).

Key Takeaway for Developers

When your MCP server isn’t connecting, don’t just check your code. Ask yourself this one critical question:

“Where is my client’s ‘brain’ running?”

If the answer is “on my machine,” stdio is your best friend. If the answer is “in the cloud,” you must treat your server as a public, secure web service and use Streamable HTTP.

Understanding this distinction will save you hours of debugging and is the key to building reliable and secure MCP integrations for any architecture.