1# Model Context Protocol
2
3## Overview
4
5The Model Context Protocol (MCP) is a JSON-RPC based protocol for communication between a client (e.g., Zed) and context servers. It enables context-aware development assistance through various features like prompts, resources, and tools.
6
7Currently, Zed's client only implements a subset of the protocol required to support custom prompt insertions and manipulations. This is likely to be expanded in the future.
8
9## Protocol Basics
10
11- Communication: JSON-RPC 2.0 over stdio
12- Versioning: Protocol version negotiated during initialization
13
14## Message Types
15
161. Requests: Client-to-server method calls
172. Responses: Server-to-client replies to requests
183. Notifications: Unidirectional messages (no response expected)
19
20## Lifecycle
21
221. Client sends `initialize` request
232. Server responds with capabilities
243. Client sends `initialized` notification
254. Normal operation begins
26
27### Initialize Request
28
29```json
30{
31 "jsonrpc": "2.0",
32 "id": 1,
33 "method": "initialize",
34 "params": {
35 "protocolVersion": 1,
36 "capabilities": {
37 "experimental": {},
38 "sampling": {}
39 },
40 "clientInfo": {
41 "name": "Zed",
42 "version": "1.0.0"
43 }
44 }
45}
46```
47
48### Initialize Response
49
50```json
51{
52 "jsonrpc": "2.0",
53 "id": 1,
54 "result": {
55 "protocolVersion": 1,
56 "capabilities": {
57 "experimental": {},
58 "logging": {},
59 "prompts": {},
60 "resources": {
61 "subscribe": true
62 },
63 "tools": {}
64 },
65 "serverInfo": {
66 "name": "ExampleServer",
67 "version": "1.0.0"
68 }
69 }
70}
71```
72
73### Initialized Notification
74
75```json
76{
77 "jsonrpc": "2.0",
78 "method": "notifications/initialized",
79 "params": {}
80}
81```
82
83## Features
84
85### Prompts
86
87#### List Prompts
88
89Request:
90
91```json
92{
93 "jsonrpc": "2.0",
94 "id": 2,
95 "method": "prompts/list",
96 "params": {}
97}
98```
99
100Response:
101
102```json
103{
104 "jsonrpc": "2.0",
105 "id": 2,
106 "result": {
107 "prompts": [
108 {
109 "name": "examplePrompt",
110 "arguments": [
111 {
112 "name": "arg1",
113 "description": "Description of arg1",
114 "required": true
115 }
116 ]
117 }
118 ]
119 }
120}
121```
122
123#### Execute Prompt
124
125Request:
126
127```json
128{
129 "jsonrpc": "2.0",
130 "id": 3,
131 "method": "prompts/get",
132 "params": {
133 "name": "examplePrompt",
134 "arguments": {
135 "arg1": "value1"
136 }
137 }
138}
139```
140
141Response:
142
143```json
144{
145 "jsonrpc": "2.0",
146 "id": 3,
147 "result": {
148 "prompt": "Generated prompt text"
149 }
150}
151```
152
153### Resources
154
155#### List Resources
156
157Request:
158
159```json
160{
161 "jsonrpc": "2.0",
162 "id": 4,
163 "method": "resources/list",
164 "params": {}
165}
166```
167
168Response:
169
170```json
171{
172 "jsonrpc": "2.0",
173 "id": 4,
174 "result": {
175 "resourceTemplates": [
176 {
177 "uriTemplate": "template://example/{param}",
178 "name": "Example Template",
179 "description": "Description of the template"
180 }
181 ],
182 "resources": [
183 {
184 "uri": "https://example.com/resource",
185 "mimeType": "text/plain"
186 }
187 ]
188 }
189}
190```
191
192#### Read Resource
193
194Request:
195
196```json
197{
198 "jsonrpc": "2.0",
199 "id": 5,
200 "method": "resources/read",
201 "params": {
202 "uri": "https://example.com/resource"
203 }
204}
205```
206
207Response:
208
209```json
210{
211 "jsonrpc": "2.0",
212 "id": 5,
213 "result": {
214 "contents": [
215 {
216 "uri": "https://example.com/resource",
217 "mimeType": "text/plain",
218 "contentType": "text",
219 "text": "Resource content"
220 }
221 ]
222 }
223}
224```
225
226#### Subscribe to Resource
227
228Request:
229
230```json
231{
232 "jsonrpc": "2.0",
233 "id": 6,
234 "method": "resources/subscribe",
235 "params": {
236 "uri": "https://example.com/resource"
237 }
238}
239```
240
241Response:
242
243```json
244{
245 "jsonrpc": "2.0",
246 "id": 6,
247 "result": null
248}
249```
250
251#### Unsubscribe from Resource
252
253Request:
254
255```json
256{
257 "jsonrpc": "2.0",
258 "id": 7,
259 "method": "resources/unsubscribe",
260 "params": {
261 "uri": "https://example.com/resource"
262 }
263}
264```
265
266Response:
267
268```json
269{
270 "jsonrpc": "2.0",
271 "id": 7,
272 "result": null
273}
274```
275
276### Tools
277
278#### Call Tool
279
280Request:
281
282```json
283{
284 "jsonrpc": "2.0",
285 "id": 8,
286 "method": "tools/call",
287 "params": {
288 "name": "exampleTool",
289 "arguments": {
290 "key": "value"
291 }
292 }
293}
294```
295
296Response:
297
298```json
299{
300 "jsonrpc": "2.0",
301 "id": 8,
302 "result": {
303 "output": "Tool execution result"
304 }
305}
306```
307
308### Logging
309
310#### Set Logging Level
311
312Request:
313
314```json
315{
316 "jsonrpc": "2.0",
317 "id": 9,
318 "method": "logging/setLevel",
319 "params": {
320 "level": "info"
321 }
322}
323```
324
325Response:
326
327```json
328{
329 "jsonrpc": "2.0",
330 "id": 9,
331 "result": null
332}
333```
334
335### Notifications
336
337#### Progress
338
339```json
340{
341 "jsonrpc": "2.0",
342 "method": "notifications/progress",
343 "params": {
344 "progressToken": "operation1",
345 "progress": 50.0,
346 "total": 100.0
347 }
348}
349```
350
351## Error Handling
352
353Errors should be returned as standard JSON-RPC 2.0 error objects:
354
355```json
356{
357 "jsonrpc": "2.0",
358 "id": null,
359 "error": {
360 "code": -32000,
361 "message": "Error message"
362 }
363}
364```