# Model Context Protocol (MCP) -- Tool Integration Standard

## META
- spec: https://modelcontextprotocol.io/specification/2025-11-25
- docs: https://modelcontextprotocol.io/docs/learn/architecture
- origin: Anthropic (Nov 2024)
- relevance: PRIMARY -- standard tool integration layer for Conductor Brain
- last_verified: 2026-02-13

## SUMMARY

MCP is an open standard for connecting AI applications to external tools, data sources, and systems. JSON-RPC 2.0 based protocol with client-server architecture. Provides standardized tool discovery, execution, and real-time updates. Adopted by major platforms (VSCode, Claude, Cursor, etc.).

## ARCHITECTURE

### Participants
```
MCP Host (AI Application)
├── MCP Client 1 → MCP Server A (tools, resources)
├── MCP Client 2 → MCP Server B (tools, resources)
└── MCP Client N → MCP Server N (tools, resources)
```

- **MCP Host**: AI application that coordinates MCP clients (e.g., Claude Desktop, VSCode, LLMHosts)
- **MCP Client**: Component maintaining connection to one MCP server
- **MCP Server**: Program providing context/tools to MCP clients

### Two Layers
1. **Data Layer**: JSON-RPC 2.0 protocol for messages, lifecycle, primitives
2. **Transport Layer**: Communication mechanisms (stdio for local, Streamable HTTP for remote)

### Transport Options
- **stdio**: Standard input/output for local processes (optimal performance, no network overhead)
- **Streamable HTTP**: HTTP POST + Server-Sent Events for remote servers (supports standard auth)

## CORE PRIMITIVES

### Server Primitives (exposed by servers)
1. **Tools**: Executable functions AI can invoke
   - Discovery: `tools/list`
   - Execution: `tools/call`
   - Notifications: `notifications/tools/list_changed`
   - Schema: JSON Schema for input validation

2. **Resources**: Data sources providing context
   - Discovery: `resources/list`
   - Retrieval: `resources/read`
   - Dynamic content (file contents, DB records, API responses)

3. **Prompts**: Reusable interaction templates
   - Discovery: `prompts/list`
   - Retrieval: `prompts/get`
   - System prompts, few-shot examples

### Client Primitives (exposed by clients)
1. **Sampling**: Servers request LLM completions from client
   - `sampling/complete`
   - Model-independent (server doesn't need LLM SDK)

2. **Elicitation**: Servers request user input
   - `elicitation/request`
   - User confirmation, additional info gathering

3. **Logging**: Servers send log messages to clients

### Utility Primitives
- **Tasks** (Experimental): Durable execution for deferred results, batch processing

## LIFECYCLE MANAGEMENT

### Initialization Handshake
```json
// Client → Server
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "elicitation": {} },
    "clientInfo": { "name": "llmhost-conductor", "version": "1.0.0" }
  }
}

// Server → Client
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": {}
    },
    "serverInfo": { "name": "llmhost-compute-node", "version": "1.0.0" }
  }
}
```

### Capability Negotiation
- Client declares supported features
- Server declares available primitives
- Only compatible features are used
- Version negotiation ensures protocol compatibility

## RELEVANCE TO LLMHOST

### MCP as Conductor ↔ Compute Node Protocol

#### Concept
Each LLMHosts compute node runs an MCP server that exposes:
- **Tools**: Available models, inference endpoints, system operations
- **Resources**: Hardware specs, current utilization, model catalog
- **Prompts**: Pre-configured system prompts, RAG templates

The Conductor Brain acts as MCP Host, connecting to all compute node MCP servers.

#### Benefits
1. **Standardized Tool Discovery**: Conductor discovers available models/tools via `tools/list`
2. **Dynamic Updates**: Nodes notify Conductor when capabilities change (`tools/list_changed`)
3. **Uniform Interface**: Same protocol for local nodes, remote VPS, and external APIs
4. **Ecosystem Compatibility**: Users can connect their own MCP servers (databases, APIs)
5. **Future-Proof**: Growing ecosystem of MCP servers adds value to LLMHosts

### Integration Architecture
```
Conductor Brain (MCP Host)
├── MCP Client → Local GPU Node (MCP Server)
│   ├── Tool: inference/chat_completion
│   ├── Tool: model/list_available
│   ├── Resource: hardware/gpu_utilization
│   └── Resource: model/cache_status
├── MCP Client → Remote VPS Node (MCP Server)
│   ├── Tool: inference/chat_completion
│   └── Resource: hardware/specs
├── MCP Client → LiteLLM Proxy (MCP Server)
│   ├── Tool: external/chat_completion
│   ├── Tool: external/list_models
│   └── Resource: external/cost_summary
└── MCP Client → User's Custom MCP Server
    ├── Tool: database/query
    └── Resource: documents/search
```

### Tool Definition Example (Compute Node)
```json
{
  "name": "inference_chat_completion",
  "title": "Chat Completion Inference",
  "description": "Run chat completion on locally served model. Supports streaming.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "model": { "type": "string", "description": "Model identifier" },
      "messages": { "type": "array", "description": "Chat messages array" },
      "temperature": { "type": "number", "default": 0.7 },
      "max_tokens": { "type": "integer", "default": 4096 },
      "stream": { "type": "boolean", "default": true }
    },
    "required": ["model", "messages"]
  }
}
```

### SDKs Available
- TypeScript/JavaScript
- Python
- Go
- Rust
- Java/Kotlin
- C#/.NET
- Swift

### Security Considerations
- Streamable HTTP transport supports OAuth, bearer tokens, API keys
- stdio transport for local (trusted) connections
- LLMHosts should use Streamable HTTP with Tailscale/Cloudflare Tunnel/Headscale overlay for remote nodes
- Token-based auth for all MCP connections through LLMHosts platform
