1# MCP Server Types: Deep Dive
2 
3Complete reference for all MCP server types supported in Claude Code plugins.
4 
5## stdio (Standard Input/Output)
6 
7### Overview
8 
9Execute local MCP servers as child processes with communication via stdin/stdout. Best choice for local tools, custom servers, and NPM packages.
10 
11### Configuration
12 
13**Basic:**
14```json
15{
16  "my-server": {
17    "command": "npx",
18    "args": ["-y", "my-mcp-server"]
19  }
20}
21```
22 
23**With environment:**
24```json
25{
26  "my-server": {
27    "command": "${CLAUDE_PLUGIN_ROOT}/servers/custom-server",
28    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
29    "env": {
30      "API_KEY": "${MY_API_KEY}",
31      "LOG_LEVEL": "debug",
32      "DATABASE_URL": "${DB_URL}"
33    }
34  }
35}
36```
37 
38### Process Lifecycle
39 
401. **Startup**: Claude Code spawns process with `command` and `args`
412. **Communication**: JSON-RPC messages via stdin/stdout
423. **Lifecycle**: Process runs for entire Claude Code session
434. **Shutdown**: Process terminated when Claude Code exits
44 
45### Use Cases
46 
47**NPM Packages:**
48```json
49{
50  "filesystem": {
51    "command": "npx",
52    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
53  }
54}
55```
56 
57**Custom Scripts:**
58```json
59{
60  "custom": {
61    "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server.js",
62    "args": ["--verbose"]
63  }
64}
65```
66 
67**Python Servers:**
68```json
69{
70  "python-server": {
71    "command": "python",
72    "args": ["-m", "my_mcp_server"],
73    "env": {
74      "PYTHONUNBUFFERED": "1"
75    }
76  }
77}
78```
79 
80### Best Practices
81 
821. **Use absolute paths or ${CLAUDE_PLUGIN_ROOT}**
832. **Set PYTHONUNBUFFERED for Python servers**
843. **Pass configuration via args or env, not stdin**
854. **Handle server crashes gracefully**
865. **Log to stderr, not stdout (stdout is for MCP protocol)**
87 
88### Troubleshooting
89 
90**Server won't start:**
91- Check command exists and is executable
92- Verify file paths are correct
93- Check permissions
94- Review `claude --debug` logs
95 
96**Communication fails:**
97- Ensure server uses stdin/stdout correctly
98- Check for stray print/console.log statements
99- Verify JSON-RPC format
100 
101## SSE (Server-Sent Events)
102 
103### Overview
104 
105Connect to hosted MCP servers via HTTP with server-sent events for streaming. Best for cloud services and OAuth authentication.
106 
107### Configuration
108 
109**Basic:**
110```json
111{
112  "hosted-service": {
113    "type": "sse",
114    "url": "https://mcp.example.com/sse"
115  }
116}
117```
118 
119**With headers:**
120```json
121{
122  "service": {
123    "type": "sse",
124    "url": "https://mcp.example.com/sse",
125    "headers": {
126      "X-API-Version": "v1",
127      "X-Client-ID": "${CLIENT_ID}"
128    }
129  }
130}
131```
132 
133### Connection Lifecycle
134 
1351. **Initialization**: HTTP connection established to URL
1362. **Handshake**: MCP protocol negotiation
1373. **Streaming**: Server sends events via SSE
1384. **Requests**: Client sends HTTP POST for tool calls
1395. **Reconnection**: Automatic reconnection on disconnect
140 
141### Authentication
142 
143**OAuth (Automatic):**
144```json
145{
146  "asana": {
147    "type": "sse",
148    "url": "https://mcp.asana.com/sse"
149  }
150}
151```
152 
153Claude Code handles OAuth flow:
1541. User prompted to authenticate on first use
1552. Opens browser for OAuth flow
1563. Tokens stored securely
1574. Automatic token refresh
158 
159**Custom Headers:**
160```json
161{
162  "service": {
163    "type": "sse",
164    "url": "https://mcp.example.com/sse",
165    "headers": {
166      "Authorization": "Bearer ${API_TOKEN}"
167    }
168  }
169}
170```
171 
172### Use Cases
173 
174**Official Services:**
175- Asana: `https://mcp.asana.com/sse`
176- GitHub: `https://mcp.github.com/sse`
177- Other hosted MCP servers
178 
179**Custom Hosted Servers:**
180Deploy your own MCP server and expose via HTTPS + SSE.
181 
182### Best Practices
183 
1841. **Always use HTTPS, never HTTP**
1852. **Let OAuth handle authentication when available**
1863. **Use environment variables for tokens**
1874. **Handle connection failures gracefully**
1885. **Document OAuth scopes required**
189 
190### Troubleshooting
191 
192**Connection refused:**
193- Check URL is correct and accessible
194- Verify HTTPS certificate is valid
195- Check network connectivity
196- Review firewall settings
197 
198**OAuth fails:**
199- Clear cached tokens
200- Check OAuth scopes
201- Verify redirect URLs
202- Re-authenticate
203 
204## HTTP (REST API)
205 
206### Overview
207 
208Connect to RESTful MCP servers via standard HTTP requests. Best for token-based auth and stateless interactions.
209 
210### Configuration
211 
212**Basic:**
213```json
214{
215  "api": {
216    "type": "http",
217    "url": "https://api.example.com/mcp"
218  }
219}
220```
221 
222**With authentication:**
223```json
224{
225  "api": {
226    "type": "http",
227    "url": "https://api.example.com/mcp",
228    "headers": {
229      "Authorization": "Bearer ${API_TOKEN}",
230      "Content-Type": "application/json",
231      "X-API-Version": "2024-01-01"
232    }
233  }
234}
235```
236 
237### Request/Response Flow
238 
2391. **Tool Discovery**: GET to discover available tools
2402. **Tool Invocation**: POST with tool name and parameters
2413. **Response**: JSON response with results or errors
2424. **Stateless**: Each request independent
243 
244### Authentication
245 
246**Token-Based:**
247```json
248{
249  "headers": {
250    "Authorization": "Bearer ${API_TOKEN}"
251  }
252}
253```
254 
255**API Key:**
256```json
257{
258  "headers": {
259    "X-API-Key": "${API_KEY}"
260  }
261}
262```
263 
264**Custom Auth:**
265```json
266{
267  "headers": {
268    "X-Auth-Token": "${AUTH_TOKEN}",
269    "X-User-ID": "${USER_ID}"
270  }
271}
272```
273 
274### Use Cases
275 
276- REST API backends
277- Internal services
278- Microservices
279- Serverless functions
280 
281### Best Practices
282 
2831. **Use HTTPS for all connections**
2842. **Store tokens in environment variables**
2853. **Implement retry logic for transient failures**
2864. **Handle rate limiting**
2875. **Set appropriate timeouts**
288 
289### Troubleshooting
290 
291**HTTP errors:**
292- 401: Check authentication headers
293- 403: Verify permissions
294- 429: Implement rate limiting
295- 500: Check server logs
296 
297**Timeout issues:**
298- Increase timeout if needed
299- Check server performance
300- Optimize tool implementations
301 
302## WebSocket (Real-time)
303 
304### Overview
305 
306Connect to MCP servers via WebSocket for real-time bidirectional communication. Best for streaming and low-latency applications.
307 
308### Configuration
309 
310**Basic:**
311```json
312{
313  "realtime": {
314    "type": "ws",
315    "url": "wss://mcp.example.com/ws"
316  }
317}
318```
319 
320**With authentication:**
321```json
322{
323  "realtime": {
324    "type": "ws",
325    "url": "wss://mcp.example.com/ws",
326    "headers": {
327      "Authorization": "Bearer ${TOKEN}",
328      "X-Client-ID": "${CLIENT_ID}"
329    }
330  }
331}
332```
333 
334### Connection Lifecycle
335 
3361. **Handshake**: WebSocket upgrade request
3372. **Connection**: Persistent bidirectional channel
3383. **Messages**: JSON-RPC over WebSocket
3394. **Heartbeat**: Keep-alive messages
3405. **Reconnection**: Automatic on disconnect
341 
342### Use Cases
343 
344- Real-time data streaming
345- Live updates and notifications
346- Collaborative editing
347- Low-latency tool calls
348- Push notifications from server
349 
350### Best Practices
351 
3521. **Use WSS (secure WebSocket), never WS**
3532. **Implement heartbeat/ping-pong**
3543. **Handle reconnection logic**
3554. **Buffer messages during disconnection**
3565. **Set connection timeouts**
357 
358### Troubleshooting
359 
360**Connection drops:**
361- Implement reconnection logic
362- Check network stability
363- Verify server supports WebSocket
364- Review firewall settings
365 
366**Message delivery:**
367- Implement message acknowledgment
368- Handle out-of-order messages
369- Buffer during disconnection
370 
371## Comparison Matrix
372 
373| Feature | stdio | SSE | HTTP | WebSocket |
374|---------|-------|-----|------|-----------|
375| **Transport** | Process | HTTP/SSE | HTTP | WebSocket |
376| **Direction** | Bidirectional | Server→Client | Request/Response | Bidirectional |
377| **State** | Stateful | Stateful | Stateless | Stateful |
378| **Auth** | Env vars | OAuth/Headers | Headers | Headers |
379| **Use Case** | Local tools | Cloud services | REST APIs | Real-time |
380| **Latency** | Lowest | Medium | Medium | Low |
381| **Setup** | Easy | Medium | Easy | Medium |
382| **Reconnect** | Process respawn | Automatic | N/A | Automatic |
383 
384## Choosing the Right Type
385 
386**Use stdio when:**
387- Running local tools or custom servers
388- Need lowest latency
389- Working with file systems or local databases
390- Distributing server with plugin
391 
392**Use SSE when:**
393- Connecting to hosted services
394- Need OAuth authentication
395- Using official MCP servers (Asana, GitHub)
396- Want automatic reconnection
397 
398**Use HTTP when:**
399- Integrating with REST APIs
400- Need stateless interactions
401- Using token-based auth
402- Simple request/response pattern
403 
404**Use WebSocket when:**
405- Need real-time updates
406- Building collaborative features
407- Low-latency critical
408- Bi-directional streaming required
409 
410## Migration Between Types
411 
412### From stdio to SSE
413 
414**Before (stdio):**
415```json
416{
417  "local-server": {
418    "command": "node",
419    "args": ["server.js"]
420  }
421}
422```
423 
424**After (SSE - deploy server):**
425```json
426{
427  "hosted-server": {
428    "type": "sse",
429    "url": "https://mcp.example.com/sse"
430  }
431}
432```
433 
434### From HTTP to WebSocket
435 
436**Before (HTTP):**
437```json
438{
439  "api": {
440    "type": "http",
441    "url": "https://api.example.com/mcp"
442  }
443}
444```
445 
446**After (WebSocket):**
447```json
448{
449  "realtime": {
450    "type": "ws",
451    "url": "wss://api.example.com/ws"
452  }
453}
454```
455 
456Benefits: Real-time updates, lower latency, bi-directional communication.
457 
458## Advanced Configuration
459 
460### Multiple Servers
461 
462Combine different types:
463 
464```json
465{
466  "local-db": {
467    "command": "npx",
468    "args": ["-y", "mcp-server-sqlite", "./data.db"]
469  },
470  "cloud-api": {
471    "type": "sse",
472    "url": "https://mcp.example.com/sse"
473  },
474  "internal-service": {
475    "type": "http",
476    "url": "https://api.example.com/mcp",
477    "headers": {
478      "Authorization": "Bearer ${API_TOKEN}"
479    }
480  }
481}
482```
483 
484### Conditional Configuration
485 
486Use environment variables to switch servers:
487 
488```json
489{
490  "api": {
491    "type": "http",
492    "url": "${API_URL}",
493    "headers": {
494      "Authorization": "Bearer ${API_TOKEN}"
495    }
496  }
497}
498```
499 
500Set different values for dev/prod:
501- Dev: `API_URL=http://localhost:8080/mcp`
502- Prod: `API_URL=https://api.production.com/mcp`
503 
504## Security Considerations
505 
506### Stdio Security
507 
508- Validate command paths
509- Don't execute user-provided commands
510- Limit environment variable access
511- Restrict file system access
512 
513### Network Security
514 
515- Always use HTTPS/WSS
516- Validate SSL certificates
517- Don't skip certificate verification
518- Use secure token storage
519 
520### Token Management
521 
522- Never hardcode tokens
523- Use environment variables
524- Rotate tokens regularly
525- Implement token refresh
526- Document scopes required
527 
528## Conclusion
529 
530Choose the MCP server type based on your use case:
531- **stdio** for local, custom, or NPM-packaged servers
532- **SSE** for hosted services with OAuth
533- **HTTP** for REST APIs with token auth
534- **WebSocket** for real-time bidirectional communication
535 
536Test thoroughly and handle errors gracefully for robust MCP integration.
537