Complete Guide to Model Context Protocol (MCP): Hosts, Clients, Transports and Tool Routing

1. The Problem Model Context Protocol (MCP) Solves

Before the introduction of the Model Context Protocol (MCP), connecting Large Language Models (LLMs) to external development environments required custom, proprietary integrations for every tool and IDE. An engineering team building a code analysis agent had to write one plugin for VS Code, another integration for Cursor, custom Webhook receivers for Claude Desktop, and proprietary function definitions for each LLM provider.

This $M \times N$ integration problem created severe architectural fragility:

• Fragmented Tool Schemas: Every provider expected slightly different JSON Schema parameters, causing frequent hallucinations when switching models.
• Process Isolation Failures: IDE plugins executed inside editor runtime threads, risking IDE crashes when executing long-running file searches or shell commands.
• Zero Portability: A developer's local toolchain configuration could not be shared cleanly across different AI coding environments without rewriting configuration manifests.

MCP standardizes this interface into an open protocol where an MCP Host (such as Cursor, VS Code, or Claude Desktop) communicates with an MCP Server over standard transport channels (such as stdio or Streamable HTTP/SSE), using structured JSON-RPC 2.0 messages.

2. Core Architectural Primitives: Host, Client, Server, and Tools

The MCP architecture separates concerns into four distinct layers:

1. MCP Host

The Host is the root application containing the developer’s active workspace and AI context. The Host orchestrates tool calls, asks user permission when necessary, and injects tool responses back into the model's active conversational window.

2. MCP Client

The Client is an internal module instantiated within the Host that manages the transport connection to a specific MCP server. It initiates the protocol handshake, polls tool capabilities via tools/list, and serializes invocations via tools/call.

3. MCP Server

The Server is an independent, lightweight process that exposes three primary capabilities:

• Tools: Executable functions with typed input schemas that perform side effects (e.g., file reads, shell commands, database queries).
• Resources: Read-only data sources (e.g., log files, database schemas) exposed via URI patterns (e.g., proxima://vault/history).
• Prompts: Pre-packaged prompt templates exposed dynamically to the model.

3. JSON-RPC 2.0 Wire Protocol & Handshake Lifecycle

Communication between Host and Server follows strict JSON-RPC 2.0 framing. Every message is a single-line JSON string terminated by a newline (\n) character across standard I/O streams.

Phase 1: Handshake (initialize & notifications/initialized)

When the IDE starts the server subprocess, it sends an initialize request declaring its client capabilities and protocol version:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "roots": { "listChanged": true },
      "sampling": {}
    },
    "clientInfo": {
      "name": "Cursor",
      "version": "0.45.0"
    }
  }
}

The Proxima MCP server responds with its server capabilities and metadata:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": { "listChanged": false },
      "resources": { "subscribe": false }
    },
    "serverInfo": {
      "name": "proxima-mcp",
      "version": "5.0.0"
    }
  }
}

Phase 2: Tool Discovery (tools/list)

The Host immediately requests all available tools to populate its function-calling context:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "read_file",
        "description": "Read file contents with optional start_line, end_line, and max_length limits.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "path": { "type": "string", "description": "Absolute file path" },
            "start_line": { "type": "integer" },
            "end_line": { "type": "integer" },
            "max_length": { "type": "integer" }
          },
          "required": ["path"]
        }
      }
    ]
  }
}

4. Transport Layer: stdio vs HTTP Streamable Transports

The MCP specification defines two standard transport mechanisms:

5. Proxima's MCP Server Implementation

In the Proxima codebase, the MCP server is initialized in proxima/src/mcp/index.js using the official @modelcontextprotocol/sdk package. The server instantiates a single McpServer instance, attaches a StdioServerTransport, and modularly registers tool suites across 6 dedicated modules.

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

// Initialize Core MCP Server Instance
const server = new McpServer({
    name: 'proxima',
    version: '5.0.0'
});

// Modular Tool Registration Across 6 Subsystems
import { register as registerChatTools } from './tools-chat.js';
import { register as registerCodeTools } from './tools-code.js';
import { register as registerSearchTools } from './tools-search.js';
import { register as registerContentTools } from './tools-content.js';
import { register as registerUtilityTools } from './tools-utility.js';
import { register as registerWorkflowTools } from './tools-workflow.js';

registerChatTools(server, deps);      // 8 Tools
registerCodeTools(server, deps);      // 12 Tools
registerSearchTools(server, deps);    // 4 Tools
registerContentTools(server, deps);   // 4 Tools
registerUtilityTools(server, deps);   // 7 Tools
registerWorkflowTools(server, deps);  // 5 Tools

// Connect to stdio duplex transport
const transport = new StdioServerTransport();
await server.connect(transport);
console.error('[MCP Server] Proxima v5.0.0 initialized on stdio transport (40 Tools registered)');

Tool Registration & Schema Validation

Every tool in Proxima uses Zod schemas for compile-time and runtime parameter validation with server.registerTool(). Consider the generate_code tool in proxima/src/mcp/tools-code.js:

server.registerTool('generate_code', {
    title: 'Generate Code',
    description: 'Generate code from description, choosing the best model (Claude by default). Supports attaching files as context or writing directly to disk.',
    inputSchema: {
        prompt: z.string().describe('What to implement — be specific about language, framework, requirements, edge cases'),
        language: z.string().optional().describe('Target language (e.g. typescript, python, rust)'),
        framework: z.string().optional().describe('Target framework (e.g. react, fastapi, express)'),
        files: z.array(z.string()).optional().describe('Optional: file paths to include as context. Supports line ranges like "path/file.js:10-50".'),
        output_file: z.string().optional().describe('Optional: file path to write generated code to'),
    },
    annotations: CODE,
}, async ({ prompt, language, framework, files, output_file }) => {
    let fullPrompt = `Generate ${language || ''} ${framework ? 'using ' + framework : ''} code:\n\n${prompt}`;
    if (output_file) {
        fullPrompt += `\n\nWrite the code cleanly. I will save this to: ${output_file}`;
    }
    const res = await smartChat({
        category: 'code',
        intent: 'generate',
        message: fullPrompt,
        preferredProvider: 'claude',
        files,
    });
    return toolResponse(res.text);
});

6. The 40 Registered Tool Catalog

A full source-code inspection of proxima/src/mcp/tools-*.js confirms exactly 40 registered MCP tools across 6 domain categories:

7. Integrating MCP with Developer IDEs (Cursor, VS Code, Windsurf)

To register Proxima's MCP server with modern AI IDEs, create or update the configuration JSON file matching your environment.

Cursor Setup (~/.cursor/mcp.json or project .cursor/mcp.json)

{
  "mcpServers": {
    "proxima": {
      "command": "node",
      "args": [
        "C:/Users/Admin/AppData/Local/Programs/Proxima/resources/app/src/mcp/index.js"
      ],
      "env": {
        "NODE_ENV": "production",
        "PROXIMA_IPC_PORT": "19222"
      }
    }
  }
}

VS Code Setup (via Claude Extension or Roo Code)

In VS Code with the Claude Dev / Cline / Roo Code extension, add the entry to mcp_settings.json:

{
  "mcpServers": {
    "proxima": {
      "command": "node",
      "args": [
        "d:/website-proxima/proxima/src/mcp/index.js"
      ]
    }
  }
}

For complete IDE-specific walkthroughs, review our dedicated guides for Cursor, VS Code, and Windsurf.

8. Failure Modes & Troubleshooting

When configuring MCP servers, developers commonly encounter four failure categories. The table below details symptoms, root causes, diagnosis steps, and verified fixes.

9. Security Boundaries & IPC Architecture

Because MCP servers can execute local shell commands and filesystem operations, security boundaries must be enforced at the process and transport layers:

• Localhost Binding Only: The IPC bridge between the MCP stdio server and Electron runs strictly over loopback address 127.0.0.1:19222. External network interfaces are never bound.
• Path Containment: File editing tools (patch_file, write_file) should enforce path validation to prevent directory traversal attacks (../../).
• Process Isolation: The MCP server runs in an unprivileged child process, isolated from the IDE's internal memory space.

10. Conclusion & Related Documentation

The Model Context Protocol establishes a clean, standardized abstraction for autonomous coding agents. By decoupling tool implementations from specific LLM providers and IDE interfaces, systems like Proxima can route 40 development tools across any modern AI workflow without vendor lock-in.