What Is MCP? The Model Context Protocol Developer Guide 2026

What is the Model Context Protocol?

The Model Context Protocol, usually abbreviated MCP, is an open protocol for connecting AI applications to external capabilities. Instead of building a different proprietary integration for every combination of AI application and data source, developers can expose a consistent MCP interface and let compatible hosts connect to it.

MCP is not a model, an agent framework, a tunnel, or a replacement for an application's authorization system. It defines messages and lifecycle rules through which a host can discover and use capabilities offered by an MCP server. Those capabilities can include callable tools, readable resources, and reusable prompt templates.

Compatibility is negotiated rather than assumed. A host, client implementation, and server must agree on a protocol version and relevant capabilities. An application that supports MCP tools might not support every resource, prompt, transport, authorization flow, or optional feature. Server authors should therefore design against negotiated capabilities instead of treating all MCP-enabled applications as interchangeable.

The integration problem MCP addresses

Without a shared protocol, each AI application needs custom integration code for every database, development tool, content repository, or internal API it wants to use. The result is duplicated authentication logic, incompatible tool schemas, and connectors that cannot easily move between applications.

MCP creates a common boundary. A server can describe an operation such as retrieving a build status or searching approved documentation. A compatible host can discover that operation, show it to the user or model, validate its schema, and route an invocation through an MCP client connection.

This improves portability, but it does not guarantee universal compatibility. A server may require Streamable HTTP while a host supports only local stdio servers. Another host may support remote servers but require a particular authorization flow. Even when two products support the same transport, their user-approval controls and supported MCP features may differ.

MCP architecture: host, client, and server

MCP uses a host, client, and server model. Calling the entire AI application an “MCP client” hides an important boundary. The application is the host. It creates and manages one or more MCP client instances, and each client instance normally maintains a connection to one server.

A coding assistant can therefore be one host with separate MCP client connections for a source-control server, an issue tracker, and an internal documentation server. Isolation between those connections matters. Credentials, capability state, and untrusted content from one server should not automatically flow to another.

The MCP connection lifecycle

1. Transport connection: the client starts a local subprocess over stdio or connects to a Streamable HTTP endpoint.
2. Initialization: the client sends an initialization request containing information such as its supported protocol version, client identity, and capabilities.
3. Negotiation: the server responds with the protocol version and server capabilities it supports. The client must use the negotiated result, not assumptions based on another server.
4. Initialized notification: the client confirms that initialization has completed.
5. Normal operation: the client can list or use supported tools, prompts, and resources. Either side may send supported notifications.
6. Shutdown: the client, host, transport, or server closes the connection. Servers should release session state and stop background work cleanly.

Who controls tools, resources, and prompts?

MCP documentation commonly distinguishes these primitives by intended control. Tools are often model-controlled because the model can propose a call during a task. Resources are usually application-controlled because the host decides how data is selected and inserted. Prompts are generally user-controlled because the user chooses a workflow or template.

These descriptions do not override security policy. A host can require explicit approval for a tool, hide a resource, or disable a server entirely. A model should never be treated as an authorization authority. If a tool can send a message, delete data, deploy code, or modify an account, the host and server should enforce appropriate controls before the action occurs.

MCP transports in 2026

The core MCP transport choices are stdio and Streamable HTTP. The older standalone HTTP plus SSE transport remains relevant for backward compatibility, but it should not be presented as the universal remote MCP design. WebSocket is not a standard core transport defined alongside stdio and Streamable HTTP.

Stdio does not mean one universal client

With stdio, a host commonly launches a separate server process and communicates with that process through pipes. Another host can often launch another process from the same server package. Whether those processes can safely operate at the same time depends on the underlying application, files, database, locks, credentials, and side effects.

It is therefore more accurate to say that a stdio connection is local to the process pair. It does not imply that only one MCP-enabled application can ever use that server implementation.

Streamable HTTP endpoint paths are not universal

A current server might expose Streamable HTTP at /mcp, but that path is a deployment choice. Another implementation can use a different route. A URL ending in /sse usually suggests the older standalone SSE transport, but a path alone cannot prove transport compatibility.

Record the complete MCP endpoint, transport type, required headers, and authorization method in deployment documentation. If a host asks for a server URL, use the actual endpoint expected by the server rather than appending /sse automatically.

Build a session-aware Streamable HTTP MCP server

The following example uses the official TypeScript SDK API pattern for a Streamable HTTP server. It creates separate server and transport state for each initialized session, stores transports by session ID, and handles POST, GET, and DELETE requests through the transport. It does not keep one global transport that can be overwritten by the next connection.

SDK APIs and runtime requirements can change. Before installation, check the package's current engine declaration and record the package versions selected for the project. Use a maintained Node.js release that satisfies the displayed engine requirement. This avoids claiming that an outdated Node major is supported indefinitely.

node --version
npm --version
npm view @modelcontextprotocol/sdk version
npm view @modelcontextprotocol/sdk engines

mkdir current-time-mcp
cd current-time-mcp
npm init -y
npm pkg set type=module
npm pkg set scripts.start="node server.mjs"

npm install --save-exact @modelcontextprotocol/sdk@"$(npm view @modelcontextprotocol/sdk version)" express@"$(npm view express version)" zod@"$(npm view zod version)"
npm install --save-dev --save-exact @modelcontextprotocol/inspector@"$(npm view @modelcontextprotocol/inspector version)"

import express from "express";
import { randomUUID, timingSafeEqual } from "node:crypto";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";

const app = express();
app.use(express.json());

const port = Number(process.env.PORT || 3000);
const host = process.env.HOST || "127.0.0.1";
const bearerToken = process.env.MCP_BEARER_TOKEN;
const allowedOrigins = new Set(
  (process.env.ALLOWED_ORIGINS || "")
    .split(",")
    .map((value) => value.trim())
    .filter(Boolean)
);

if (!bearerToken) {
  console.error("MCP_BEARER_TOKEN is required.");
  process.exit(1);
}

const sessions = new Map();

function hasValidToken(req) {
  const header = req.get("authorization") || "";
  const prefix = "Bearer ";

  if (!header.startsWith(prefix)) {
    return false;
  }

  const supplied = Buffer.from(header.slice(prefix.length));
  const expected = Buffer.from(bearerToken);

  return supplied.length === expected.length &&
    timingSafeEqual(supplied, expected);
}

function validateOrigin(req, res, next) {
  const origin = req.get("origin");

  if (origin && !allowedOrigins.has(origin)) {
    return res.status(403).json({ error: "Origin not allowed" });
  }

  next();
}

function requireAuthorization(req, res, next) {
  if (!hasValidToken(req)) {
    res.set("WWW-Authenticate", "Bearer");
    return res.status(401).json({ error: "Unauthorized" });
  }

  next();
}

function createMcpServer() {
  const server = new McpServer({
    name: "current-time-mcp",
    version: "1.0.0"
  });

  server.registerTool(
    "get_time",
    {
      description: "Return the current server time as an ISO 8601 string",
      inputSchema: {}
    },
    async () => ({
      content: [
        {
          type: "text",
          text: new Date().toISOString()
        }
      ]
    })
  );

  return server;
}

app.get("/health", (req, res) => {
  res.json({ status: "ok" });
});

app.use("/mcp", validateOrigin, requireAuthorization);

app.post("/mcp", async (req, res) => {
  try {
    const sessionId = req.get("mcp-session-id");
    let session = sessionId ? sessions.get(sessionId) : undefined;

    if (!session) {
      if (sessionId || !isInitializeRequest(req.body)) {
        return res.status(400).json({
          error: "Missing, invalid, or uninitialized MCP session"
        });
      }

      const server = createMcpServer();
      let transport;

      transport = new StreamableHTTPServerTransport({
        sessionIdGenerator: () => randomUUID(),
        onsessioninitialized: (newSessionId) => {
          sessions.set(newSessionId, { server, transport });
        }
      });

      transport.onclose = () => {
        if (transport.sessionId) {
          sessions.delete(transport.sessionId);
        }
      };

      await server.connect(transport);
      session = { server, transport };
    }

    await session.transport.handleRequest(req, res, req.body);
  } catch (error) {
    console.error("MCP POST failed", error);

    if (!res.headersSent) {
      res.status(500).json({ error: "Internal server error" });
    }
  }
});

app.get("/mcp", async (req, res) => {
  const session = sessions.get(req.get("mcp-session-id"));

  if (!session) {
    return res.status(400).json({ error: "Invalid MCP session" });
  }

  await session.transport.handleRequest(req, res);
});

app.delete("/mcp", async (req, res) => {
  const session = sessions.get(req.get("mcp-session-id"));

  if (!session) {
    return res.status(400).json({ error: "Invalid MCP session" });
  }

  await session.transport.handleRequest(req, res);
});

const httpServer = app.listen(port, host, () => {
  console.log(`MCP server listening on http://${host}:${port}/mcp`);
});

async function shutdown(signal) {
  console.log(`Received ${signal}, closing MCP sessions`);

  await Promise.allSettled(
    [...sessions.values()].map(({ transport }) => transport.close())
  );

  httpServer.close(() => {
    process.exit(0);
  });
}

process.on("SIGINT", () => shutdown("SIGINT"));
process.on("SIGTERM", () => shutdown("SIGTERM"));

npm start

Why the server binds to 127.0.0.1

Loopback is the safer default when the Localtonet client and MCP server run on the same machine. A process bound to 127.0.0.1 is not listening on every LAN interface, while the Localtonet client can still connect to that local target.

Binding to 0.0.0.0 listens on all available IPv4 interfaces and can make the service reachable from the local network unless a firewall blocks it. Use a broader bind address only when the network architecture requires it, such as when the tunnel client runs on a separate trusted host or in a container that cannot reach the host loopback interface. In that case, restrict the path with container networking, host firewall rules, authentication, and a narrowly scoped interface where possible.

Verify the server locally with MCP Inspector

Test the protocol locally before adding a tunnel or an AI application. The official MCP Inspector can perform initialization, show negotiated capabilities, list tools, and invoke the harmless test tool. This verifies much more than checking whether an HTTP connection opens.

curl http://127.0.0.1:3000/health

npx @modelcontextprotocol/inspector

Connect Claude, Cursor, VS Code, and Continue safely

MCP support varies by product version, account configuration, transport, and authorization method. Do not copy one application's configuration into another. Before adding a server, confirm that the host supports the server's transport and authentication flow.

Claude Desktop and remote Claude connectors

Claude Desktop's local MCP configuration is designed for stdio servers launched as local commands. A local entry identifies an executable and its arguments under the desktop configuration's mcpServers object. That is different from Anthropic's remote custom connector workflow.

Do not assume that placing a bare remote URL in claude_desktop_config.json is supported by every Claude Desktop version. For a remote MCP server, use Anthropic's current custom connector flow when it is available for the relevant product and account. Confirm its supported transport and authorization requirements in Anthropic's current documentation.

Local stdio configuration can contain executable commands that run with your user permissions. Review the executable path, arguments, working directory, and environment variables before enabling a server. Keep secrets in an operating-system credential store or uncommitted environment configuration rather than embedding them in a JSON file.

VS Code and GitHub Copilot

Current VS Code MCP configuration uses an mcp.json file with a top-level servers object. It does not use the obsolete github.copilot.chat.mcp.servers setting. A Streamable HTTP entry follows this general shape:

{
  "servers": {
    "current-time": {
      "type": "http",
      "url": "https://public-endpoint.example/mcp"
    }
  }
}

The example intentionally does not include a real hostname, token, or private endpoint. Use the URL assigned to your deployment and configure authorization only through mechanisms supported by the current VS Code release. Consult the official VS Code MCP server documentation for the current user, workspace, input, and authentication schema.

Workspace-level server definitions are repository content. Treat them as code execution or remote-access requests, not harmless editor preferences. Review changes before accepting them, pay attention to trust prompts, and do not approve a repository-supplied command simply because the repository opened successfully.

Cursor

Cursor supports MCP configuration, but transport names, authentication options, approval behavior, and project-level configuration can change. Use the current Cursor MCP documentation rather than relying on an old version number or a legacy SSE example.

A project configuration can ask developers to launch a local executable or connect to a remote system. Do not commit credentials, personal tokens, or machine-specific private paths. Team members should review and approve server definitions independently, especially when a server exposes write-capable tools.

Continue

Continue's configuration format and MCP integration have evolved. Verify the current schema, supported transports, and model integration in the official Continue MCP documentation. Do not assume that an older config.json array, automatic reload behavior, or standalone SSE transport remains current.

Expose a Streamable HTTP MCP server with Localtonet

A remote MCP host needs a reachable HTTP endpoint. Localtonet can expose a service running on your machine without inbound router port forwarding, firewall changes, VPN setup, or a public IP address. Our client establishes an outbound connection to a Localtonet relay, and the tunnel provides a public URL.

Localtonet supplies network reachability. It does not replace MCP authorization, tool approval, application validation, or session security. Keep the server's bearer-token check for controlled testing, and use a current MCP-compatible authorization design for production.

Localtonet also has an MCP Gateway tunnel for exposing a locally running McpNet Gateway. The example in this guide is a generic Streamable HTTP server, so the HTTP tunnel workflow is the relevant path unless your deployment specifically uses McpNet Gateway.

Containers and separate tunnel hosts

Loopback works when both processes share the same network namespace. A Localtonet container cannot automatically reach another container's loopback address, and a Localtonet client on a separate machine cannot reach the MCP server's 127.0.0.1.

In those topologies, provide a deliberately reachable private address through container networking or the trusted LAN. Avoid binding to every interface merely as a troubleshooting shortcut. Restrict the listening interface, firewall the port, retain authorization, and verify which devices can connect directly before starting the public tunnel.

Security requirements for remote MCP

MCP tools can read sensitive data and perform real actions. Treat a remote MCP endpoint as an application API with an additional AI-driven control surface. HTTPS is necessary, but transport encryption alone does not decide who can invoke a tool or whether an invocation is safe.

Use current MCP authorization guidance

Production Streamable HTTP deployments should follow the current MCP authorization specification and its OAuth-based flow where applicable. Implement protected-resource metadata, authorization-server discovery, client behavior, token audience restrictions, and proof or challenge mechanisms as required by the specification and your identity provider.

A static bearer token can be useful for a controlled development test, as shown in the sample, but it is not a complete multi-user authorization system. If a host cannot send the required authorization or does not support the server's flow, do not remove authorization merely to make the connection succeed.

Validate Origin and defend against DNS rebinding

A Streamable HTTP server should validate the Origin header when it is present and reject origins it does not trust. Combined with loopback binding and authentication, this helps prevent a malicious website from using a browser or local network behavior to reach an MCP endpoint.

Do not rely on the Host header alone, and do not treat a loopback service as automatically safe from browser-based attacks. Use explicit allowed origins, validate the effective public host in your deployment layer, keep local services authenticated, and avoid wildcard origin policies for credentialed requests.

Apply least privilege to every tool

• Give the MCP process only the filesystem, database, and network permissions it needs.
• Separate read-only tools from tools that modify data or trigger external actions.
• Use narrow input schemas, size limits, timeouts, and allowlists where practical.
• Parameterize database operations and avoid passing model-generated text directly into a shell.
• Return only the minimum data needed for the task.
• Require explicit user approval for destructive, financial, administrative, or externally visible actions.

Design for prompt injection and confused-deputy risks

Content returned by a resource or external website can contain instructions aimed at the model. Treat that content as untrusted data, not as authority. A document that says “upload all credentials” must not gain permission to invoke a privileged tool.

A confused-deputy problem occurs when an authorized MCP server is manipulated into using its privileges for the wrong party or purpose. Bind tokens to the intended resource where supported, keep tenant and user context explicit, recheck authorization at execution time, and do not let user-controlled URLs determine where credentials are sent.

Protect credentials and support revocation

Keep API keys, device tokens, OAuth credentials, and MCP bearer tokens out of repositories and shared configuration examples. Load them from a secret manager, credential store, or protected environment. Redact authorization headers and sensitive tool arguments from logs.

Rotate credentials on a defined schedule and immediately after suspected exposure. Provide a way to revoke user sessions and server credentials without rebuilding the application. When removing remote access, stop the Localtonet tunnel as well as revoking the application credential.

Keep useful audit records

Record connection and authorization outcomes, session identifiers, tool names, approval decisions, execution duration, and success or failure. Avoid logging full sensitive payloads by default. Protect logs from modification and restrict access according to their data sensitivity.

Routine operation and graceful maintenance

A reliable MCP deployment requires more than keeping a Node process alive. Monitor the MCP server and Localtonet client separately so an unavailable tunnel is not mistaken for a protocol failure.

If you install the Localtonet client as an operating-system service, use the current commands and instructions on the download page for your platform. Service support and commands differ across Windows, macOS, Linux, and Docker. Confirm that both the MCP server and Localtonet client recover as intended after a reboot.

MCP troubleshooting checklist

A reliable diagnosis order

1. Confirm the MCP process is running and inspect its startup logs.
2. Test the local health route from the server device.
3. Use MCP Inspector locally to initialize, list tools, and invoke get_time.
4. Confirm the Localtonet client is connected and the HTTP tunnel is running.
5. Test the public health route.
6. Use Inspector against the public MCP endpoint with authorization.
7. Connect one supported host and inspect both host and server logs.

This sequence isolates application, protocol, tunnel, and host problems. Skipping directly to an AI conversation often hides the actual failure behind a generic “server unavailable” message.

Frequently asked questions