Model Context Protocol in OCaml
anil.recoil.org
1---
2title: Resources
3type: docs
4weight: 20
5---
6
7{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}}
8
9The Model Context Protocol (MCP) provides a standardized way for servers to expose
10resources to clients. Resources allow servers to share data that provides context to
11language models, such as files, database schemas, or application-specific information.
12Each resource is uniquely identified by a
13[URI](https://datatracker.ietf.org/doc/html/rfc3986).
14
15## User Interaction Model
16
17Resources in MCP are designed to be **application-driven**, with host applications
18determining how to incorporate context based on their needs.
19
20For example, applications could:
21
22- Expose resources through UI elements for explicit selection, in a tree or list view
23- Allow the user to search through and filter available resources
24- Implement automatic context inclusion, based on heuristics or the AI model's selection
25
26
27
28However, implementations are free to expose resources through any interface pattern that
29suits their needs—the protocol itself does not mandate any specific user
30interaction model.
31
32## Capabilities
33
34Servers that support resources **MUST** declare the `resources` capability:
35
36```json
37{
38 "capabilities": {
39 "resources": {
40 "subscribe": true,
41 "listChanged": true
42 }
43 }
44}
45```
46
47The capability supports two optional features:
48
49- `subscribe`: whether the client can subscribe to be notified of changes to individual
50 resources.
51- `listChanged`: whether the server will emit notifications when the list of available
52 resources changes.
53
54Both `subscribe` and `listChanged` are optional—servers can support neither,
55either, or both:
56
57```json
58{
59 "capabilities": {
60 "resources": {} // Neither feature supported
61 }
62}
63```
64
65```json
66{
67 "capabilities": {
68 "resources": {
69 "subscribe": true // Only subscriptions supported
70 }
71 }
72}
73```
74
75```json
76{
77 "capabilities": {
78 "resources": {
79 "listChanged": true // Only list change notifications supported
80 }
81 }
82}
83```
84
85## Protocol Messages
86
87### Listing Resources
88
89To discover available resources, clients send a `resources/list` request. This operation
90supports [pagination]({{< ref "utilities/pagination" >}}).
91
92**Request:**
93
94```json
95{
96 "jsonrpc": "2.0",
97 "id": 1,
98 "method": "resources/list",
99 "params": {
100 "cursor": "optional-cursor-value"
101 }
102}
103```
104
105**Response:**
106
107```json
108{
109 "jsonrpc": "2.0",
110 "id": 1,
111 "result": {
112 "resources": [
113 {
114 "uri": "file:///project/src/main.rs",
115 "name": "main.rs",
116 "description": "Primary application entry point",
117 "mimeType": "text/x-rust"
118 }
119 ],
120 "nextCursor": "next-page-cursor"
121 }
122}
123```
124
125### Reading Resources
126
127To retrieve resource contents, clients send a `resources/read` request:
128
129**Request:**
130
131```json
132{
133 "jsonrpc": "2.0",
134 "id": 2,
135 "method": "resources/read",
136 "params": {
137 "uri": "file:///project/src/main.rs"
138 }
139}
140```
141
142**Response:**
143
144```json
145{
146 "jsonrpc": "2.0",
147 "id": 2,
148 "result": {
149 "contents": [
150 {
151 "uri": "file:///project/src/main.rs",
152 "mimeType": "text/x-rust",
153 "text": "fn main() {\n println!(\"Hello world!\");\n}"
154 }
155 ]
156 }
157}
158```
159
160### Resource Templates
161
162Resource templates allow servers to expose parameterized resources using
163[URI templates](https://datatracker.ietf.org/doc/html/rfc6570). Arguments may be
164auto-completed through [the completion API]({{< ref "utilities/completion" >}}).
165
166**Request:**
167
168```json
169{
170 "jsonrpc": "2.0",
171 "id": 3,
172 "method": "resources/templates/list"
173}
174```
175
176**Response:**
177
178```json
179{
180 "jsonrpc": "2.0",
181 "id": 3,
182 "result": {
183 "resourceTemplates": [
184 {
185 "uriTemplate": "file:///{path}",
186 "name": "Project Files",
187 "description": "Access files in the project directory",
188 "mimeType": "application/octet-stream"
189 }
190 ]
191 }
192}
193```
194
195### List Changed Notification
196
197When the list of available resources changes, servers that declared the `listChanged`
198capability **SHOULD** send a notification:
199
200```json
201{
202 "jsonrpc": "2.0",
203 "method": "notifications/resources/list_changed"
204}
205```
206
207### Subscriptions
208
209The protocol supports optional subscriptions to resource changes. Clients can subscribe
210to specific resources and receive notifications when they change:
211
212**Subscribe Request:**
213
214```json
215{
216 "jsonrpc": "2.0",
217 "id": 4,
218 "method": "resources/subscribe",
219 "params": {
220 "uri": "file:///project/src/main.rs"
221 }
222}
223```
224
225**Update Notification:**
226
227```json
228{
229 "jsonrpc": "2.0",
230 "method": "notifications/resources/updated",
231 "params": {
232 "uri": "file:///project/src/main.rs"
233 }
234}
235```
236
237## Message Flow
238
239```mermaid
240sequenceDiagram
241 participant Client
242 participant Server
243
244 Note over Client,Server: Resource Discovery
245 Client->>Server: resources/list
246 Server-->>Client: List of resources
247
248 Note over Client,Server: Resource Access
249 Client->>Server: resources/read
250 Server-->>Client: Resource contents
251
252 Note over Client,Server: Subscriptions
253 Client->>Server: resources/subscribe
254 Server-->>Client: Subscription confirmed
255
256 Note over Client,Server: Updates
257 Server--)Client: notifications/resources/updated
258 Client->>Server: resources/read
259 Server-->>Client: Updated contents
260```
261
262## Data Types
263
264### Resource
265
266A resource definition includes:
267
268- `uri`: Unique identifier for the resource
269- `name`: Human-readable name
270- `description`: Optional description
271- `mimeType`: Optional MIME type
272- `size`: Optional size in bytes
273
274### Resource Contents
275
276Resources can contain either text or binary data:
277
278#### Text Content
279
280```json
281{
282 "uri": "file:///example.txt",
283 "mimeType": "text/plain",
284 "text": "Resource content"
285}
286```
287
288#### Binary Content
289
290```json
291{
292 "uri": "file:///example.png",
293 "mimeType": "image/png",
294 "blob": "base64-encoded-data"
295}
296```
297
298## Common URI Schemes
299
300The protocol defines several standard URI schemes. This list not
301exhaustive—implementations are always free to use additional, custom URI schemes.
302
303### https://
304
305Used to represent a resource available on the web.
306
307Servers **SHOULD** use this scheme only when the client is able to fetch and load the
308resource directly from the web on its own—that is, it doesn’t need to read the resource
309via the MCP server.
310
311For other use cases, servers **SHOULD** prefer to use another URI scheme, or define a
312custom one, even if the server will itself be downloading resource contents over the
313internet.
314
315### file://
316
317Used to identify resources that behave like a filesystem. However, the resources do not
318need to map to an actual physical filesystem.
319
320MCP servers **MAY** identify file:// resources with an
321[XDG MIME type](https://specifications.freedesktop.org/shared-mime-info-spec/0.14/ar01s02.html#id-1.3.14),
322like `inode/directory`, to represent non-regular files (such as directories) that don’t
323otherwise have a standard MIME type.
324
325### git://
326
327Git version control integration.
328
329## Error Handling
330
331Servers **SHOULD** return standard JSON-RPC errors for common failure cases:
332
333- Resource not found: `-32002`
334- Internal errors: `-32603`
335
336Example error:
337
338```json
339{
340 "jsonrpc": "2.0",
341 "id": 5,
342 "error": {
343 "code": -32002,
344 "message": "Resource not found",
345 "data": {
346 "uri": "file:///nonexistent.txt"
347 }
348 }
349}
350```
351
352## Security Considerations
353
3541. Servers **MUST** validate all resource URIs
3552. Access controls **SHOULD** be implemented for sensitive resources
3563. Binary data **MUST** be properly encoded
3574. Resource permissions **SHOULD** be checked before operations