Model Context Protocol in OCaml
anil.recoil.org
1---
2title: Architecture
3cascade:
4 type: docs
5weight: 10
6---
7
8The Model Context Protocol (MCP) follows a client-host-server architecture where each
9host can run multiple client instances. This architecture enables users to integrate AI
10capabilities across applications while maintaining clear security boundaries and
11isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused
12on context exchange and sampling coordination between clients and servers.
13
14## Core Components
15
16```mermaid
17graph LR
18 subgraph "Application Host Process"
19 H[Host]
20 C1[Client 1]
21 C2[Client 2]
22 C3[Client 3]
23 H --> C1
24 H --> C2
25 H --> C3
26 end
27
28 subgraph "Local machine"
29 S1[Server 1<br>Files & Git]
30 S2[Server 2<br>Database]
31 R1[("Local<br>Resource A")]
32 R2[("Local<br>Resource B")]
33
34 C1 --> S1
35 C2 --> S2
36 S1 <--> R1
37 S2 <--> R2
38 end
39
40 subgraph "Internet"
41 S3[Server 3<br>External APIs]
42 R3[("Remote<br>Resource C")]
43
44 C3 --> S3
45 S3 <--> R3
46 end
47```
48
49### Host
50
51The host process acts as the container and coordinator:
52
53- Creates and manages multiple client instances
54- Controls client connection permissions and lifecycle
55- Enforces security policies and consent requirements
56- Handles user authorization decisions
57- Coordinates AI/LLM integration and sampling
58- Manages context aggregation across clients
59
60### Clients
61
62Each client is created by the host and maintains an isolated server connection:
63
64- Establishes one stateful session per server
65- Handles protocol negotiation and capability exchange
66- Routes protocol messages bidirectionally
67- Manages subscriptions and notifications
68- Maintains security boundaries between servers
69
70A host application creates and manages multiple clients, with each client having a 1:1
71relationship with a particular server.
72
73### Servers
74
75Servers provide specialized context and capabilities:
76
77- Expose resources, tools and prompts via MCP primitives
78- Operate independently with focused responsibilities
79- Request sampling through client interfaces
80- Must respect security constraints
81- Can be local processes or remote services
82
83## Design Principles
84
85MCP is built on several key design principles that inform its architecture and
86implementation:
87
881. **Servers should be extremely easy to build**
89
90 - Host applications handle complex orchestration responsibilities
91 - Servers focus on specific, well-defined capabilities
92 - Simple interfaces minimize implementation overhead
93 - Clear separation enables maintainable code
94
952. **Servers should be highly composable**
96
97 - Each server provides focused functionality in isolation
98 - Multiple servers can be combined seamlessly
99 - Shared protocol enables interoperability
100 - Modular design supports extensibility
101
1023. **Servers should not be able to read the whole conversation, nor "see into" other
103 servers**
104
105 - Servers receive only necessary contextual information
106 - Full conversation history stays with the host
107 - Each server connection maintains isolation
108 - Cross-server interactions are controlled by the host
109 - Host process enforces security boundaries
110
1114. **Features can be added to servers and clients progressively**
112 - Core protocol provides minimal required functionality
113 - Additional capabilities can be negotiated as needed
114 - Servers and clients evolve independently
115 - Protocol designed for future extensibility
116 - Backwards compatibility is maintained
117
118## Capability Negotiation
119
120The Model Context Protocol uses a capability-based negotiation system where clients and
121servers explicitly declare their supported features during initialization. Capabilities
122determine which protocol features and primitives are available during a session.
123
124- Servers declare capabilities like resource subscriptions, tool support, and prompt
125 templates
126- Clients declare capabilities like sampling support and notification handling
127- Both parties must respect declared capabilities throughout the session
128- Additional capabilities can be negotiated through extensions to the protocol
129
130```mermaid
131sequenceDiagram
132 participant Host
133 participant Client
134 participant Server
135
136 Host->>+Client: Initialize client
137 Client->>+Server: Initialize session with capabilities
138 Server-->>Client: Respond with supported capabilities
139
140 Note over Host,Server: Active Session with Negotiated Features
141
142 loop Client Requests
143 Host->>Client: User- or model-initiated action
144 Client->>Server: Request (tools/resources)
145 Server-->>Client: Response
146 Client-->>Host: Update UI or respond to model
147 end
148
149 loop Server Requests
150 Server->>Client: Request (sampling)
151 Client->>Host: Forward to AI
152 Host-->>Client: AI response
153 Client-->>Server: Response
154 end
155
156 loop Notifications
157 Server--)Client: Resource updates
158 Client--)Server: Status changes
159 end
160
161 Host->>Client: Terminate
162 Client->>-Server: End session
163 deactivate Server
164```
165
166Each capability unlocks specific protocol features for use during the session. For
167example:
168
169- Implemented [server features]({{< ref "../server" >}}) must be advertised in the
170 server's capabilities
171- Emitting resource subscription notifications requires the server to declare
172 subscription support
173- Tool invocation requires the server to declare tool capabilities
174- [Sampling]({{< ref "../client" >}}) requires the client to declare support in its
175 capabilities
176
177This capability negotiation ensures clients and servers have a clear understanding of
178supported functionality while maintaining protocol extensibility.