mcp-integration

Name: mcp-integration
Author: anthropics

byanthropics· 237 skills

Installs

13k

Stars

139k

Forks

22k

How to install mcp-integration?

anthropics/claude-code/mcp-integration

$npx -y skills add anthropics/claude-code --skill mcp-integration

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/anthropics/claude-code" --skill "anthropics/claude-code/mcp-integration"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/anthropics/claude-code" that are relevant to the current task. Run `npx skills add "https://github.com/anthropics/claude-code"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# MCP Integration for Claude Code Plugins
2
3	## Overview
4
5	Model Context Protocol (MCP) enables Claude Code plugins to integrate with external services and APIs by providing structured tool access. Use MCP integration to expose external service capabilities as tools within Claude Code.
6
7	Key capabilities:
8	- Connect to external services (databases, APIs, file systems)
9	- Provide 10+ related tools from a single service
10	- Handle OAuth and complex authentication flows
11	- Bundle MCP servers with plugins for automatic setup
12
13	## MCP Server Configuration Methods
14
15	Plugins can bundle MCP servers in two ways:
16
17	### Method 1: Dedicated .mcp.json (Recommended)
18
19	Create `.mcp.json` at plugin root:
20
21	```json
22	{
23	"database-tools": {
24	"command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
25	"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
26	"env": {
27	"DB_URL": "${DB_URL}"
28	}
29	}
30	}
31	```
32
33	Benefits:
34	- Clear separation of concerns
35	- Easier to maintain
36	- Better for multiple servers
37
38	### Method 2: Inline in plugin.json
39
40	Add `mcpServers` field to plugin.json:
41
42	```json
43	{
44	"name": "my-plugin",
45	"version": "1.0.0",
46	"mcpServers": {
47	"plugin-api": {
48	"command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
49	"args": ["--port", "8080"]
50	}
51	}
52	}
53	```
54
55	Benefits:
56	- Single configuration file
57	- Good for simple single-server plugins
58
59	## MCP Server Types
60
61	### stdio (Local Process)
62
63	Execute local MCP servers as child processes. Best for local tools and custom servers.
64
65	Configuration:
66	```json
67	{
68	"filesystem": {
69	"command": "npx",
70	"args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
71	"env": {
72	"LOG_LEVEL": "debug"
73	}
74	}
75	}
76	```
77
78	Use cases:
79	- File system access
80	- Local database connections
81	- Custom MCP servers
82	- NPM-packaged MCP servers
83
84	Process management:
85	- Claude Code spawns and manages the process
86	- Communicates via stdin/stdout
87	- Terminates when Claude Code exits
88
89	### SSE (Server-Sent Events)
90
91	Connect to hosted MCP servers with OAuth support. Best for cloud services.
92
93	Configuration:
94	```json
95	{
96	"asana": {
97	"type": "sse",
98	"url": "https://mcp.asana.com/sse"
99	}
100	}
101	```
102
103	Use cases:
104	- Official hosted MCP servers (Asana, GitHub, etc.)
105	- Cloud services with MCP endpoints
106	- OAuth-based authentication
107	- No local installation needed
108
109	Authentication:
110	- OAuth flows handled automatically
111	- User prompted on first use
112	- Tokens managed by Claude Code
113
114	### HTTP (REST API)
115
116	Connect to RESTful MCP servers with token authentication.
117
118	Configuration:
119	```json
120	{
121	"api-service": {
122	"type": "http",
123	"url": "https://api.example.com/mcp",
124	"headers": {
125	"Authorization": "Bearer ${API_TOKEN}",
126	"X-Custom-Header": "value"
127	}
128	}
129	}
130	```
131
132	Use cases:
133	- REST API-based MCP servers
134	- Token-based authentication
135	- Custom API backends
136	- Stateless interactions
137
138	### WebSocket (Real-time)
139
140	Connect to WebSocket MCP servers for real-time bidirectional communication.
141
142	Configuration:
143	```json
144	{
145	"realtime-service": {
146	"type": "ws",
147	"url": "wss://mcp.example.com/ws",
148	"headers": {
149	"Authorization": "Bearer ${TOKEN}"
150	}
151	}
152	}
153	```
154
155	Use cases:
156	- Real-time data streaming
157	- Persistent connections
158	- Push notifications from server
159	- Low-latency requirements
160
161	## Environment Variable Expansion
162
163	All MCP configurations support environment variable substitution:
164
165	${CLAUDE_PLUGIN_ROOT} - Plugin directory (always use for portability):
166	```json
167	{
168	"command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server"
169	}
170	```
171
172	User environment variables - From user's shell:
173	```json
174	{
175	"env": {
176	"API_KEY": "${MY_API_KEY}",
177	"DATABASE_URL": "${DB_URL}"
178	}
179	}
180	```
181
182	Best practice: Document all required environment variables in plugin README.
183
184	## MCP Tool Naming
185
186	When MCP servers provide tools, they're automatically prefixed:
187
188	Format: `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`
189
190	Example:
191	- Plugin: `asana`
192	- Server: `asana`
193	- Tool: `create_task`
194	- Full name: `mcp__plugin_asana_asana__asana_create_task`
195
196	### Using MCP Tools in Commands
197
198	Pre-allow specific MCP tools in command frontmatter:
199
200	```markdown
201	---
202	allowed-tools: [
203	"mcp__plugin_asana_asana__asana_create_task",
204	"mcp__plugin_asana_asana__asana_search_tasks"
205	]
206	---
207	```
208
209	Wildcard (use sparingly):
210	```markdown
211	---
212	allowed-tools: ["mcp__plugin_asana_asana__*"]
213	---
214	```
215
216	Best practice: Pre-allow specific tools, not wildcards, for security.
217
218	## Lifecycle Management
219
220	Automatic startup:
221	- MCP servers start when plugin enables
222	- Connection established before first tool use
223	- Restart required for configuration changes
224
225	Lifecycle:
226	1. Plugin loads
227	2. MCP configuration parsed
228	3. Server process started (stdio) or connection established (SSE/HTTP/WS)
229	4. Tools discovered and registered
230	5. Tools available as `mcp__plugin_...__...`
231
232	Viewing servers:
233	Use `/mcp` command to see all servers including plugin-provided ones.
234
235	## Authentication Patterns
236
237	### OAuth (SSE/HTTP)
238
239	OAuth handled automatically by Claude Code:
240
241	```json
242	{
243	"type": "sse",
244	"url": "https://mcp.example.com/sse"
245	}
246	```
247
248	User authenticates in browser on first use. No additional configuration needed.
249
250	### Token-Based (Headers)
251
252	Static or environment variable tokens:
253
254	```json
255	{
256	"type": "http",
257	"url": "https://api.example.com",
258	"headers": {
259	"Authorization": "Bearer ${API_TOKEN}"
260	}
261	}
262	```
263
264	Document required environment variables in README.
265
266	### Environment Variables (stdio)
267
268	Pass configuration to MCP server:
269
270	```json
271	{
272	"command": "python",
273	"args": ["-m", "my_mcp_server"],
274	"env": {
275	"DATABASE_URL": "${DB_URL}",
276	"API_KEY": "${API_KEY}",
277	"LOG_LEVEL": "info"
278	}
279	}
280	```
281
282	## Integration Patterns
283
284	### Pattern 1: Simple Tool Wrapper
285
286	Commands use MCP tools with user interaction:
287
288	```markdown
289	# Command: create-item.md
290	---
291	allowed-tools: ["mcp__plugin_name_server__create_item"]
292	---
293
294	Steps:
295	1. Gather item details from user
296	2. Use mcp__plugin_name_server__create_item
297	3. Confirm creation
298	```
299
300	Use for: Adding validation or preprocessing before MCP calls.
301
302	### Pattern 2: Autonomous Agent
303
304	Agents use MCP tools autonomously:
305
306	```markdown
307	# Agent: data-analyzer.md
308
309	Analysis Process:
310	1. Query data via mcp__plugin_db_server__query
311	2. Process and analyze results
312	3. Generate insights report
313	```
314
315	Use for: Multi-step MCP workflows without user interaction.
316
317	### Pattern 3: Multi-Server Plugin
318
319	Integrate multiple MCP servers:
320
321	```json
322	{
323	"github": {
324	"type": "sse",
325	"url": "https://mcp.github.com/sse"
326	},
327	"jira": {
328	"type": "sse",
329	"url": "https://mcp.jira.com/sse"
330	}
331	}
332	```
333
334	Use for: Workflows spanning multiple services.
335
336	## Security Best Practices
337
338	### Use HTTPS/WSS
339
340	Always use secure connections:
341
342	```json
343	✅ "url": "https://mcp.example.com/sse"
344	❌ "url": "http://mcp.example.com/sse"
345	```
346
347	### Token Management
348
349	DO:
350	- ✅ Use environment variables for tokens
351	- ✅ Document required env vars in README
352	- ✅ Let OAuth flow handle authentication
353
354	DON'T:
355	- ❌ Hardcode tokens in configuration
356	- ❌ Commit tokens to git
357	- ❌ Share tokens in documentation
358
359	### Permission Scoping
360
361	Pre-allow only necessary MCP tools:
362
363	```markdown
364	✅ allowed-tools: [
365	"mcp__plugin_api_server__read_data",
366	"mcp__plugin_api_server__create_item"
367	]
368
369	❌ allowed-tools: ["mcp__plugin_api_server__*"]
370	```
371
372	## Error Handling
373
374	### Connection Failures
375
376	Handle MCP server unavailability:
377	- Provide fallback behavior in commands
378	- Inform user of connection issues
379	- Check server URL and configuration
380
381	### Tool Call Errors
382
383	Handle failed MCP operations:
384	- Validate inputs before calling MCP tools
385	- Provide clear error messages
386	- Check rate limiting and quotas
387
388	### Configuration Errors
389
390	Validate MCP configuration:
391	- Test server connectivity during development
392	- Validate JSON syntax
393	- Check required environment variables
394
395	## Performance Considerations
396
397	### Lazy Loading
398
399	MCP servers connect on-demand:
400	- Not all servers connect at startup
401	- First tool use triggers connection
402	- Connection pooling managed automatically
403
404	### Batching
405
406	Batch similar requests when possible:
407
408	```
409	# Good: Single query with filters
410	tasks = search_tasks(project="X", assignee="me", limit=50)
411
412	# Avoid: Many individual queries
413	for id in task_ids:
414	task = get_task(id)
415	```
416
417	## Testing MCP Integration
418
419	### Local Testing
420
421	1. Configure MCP server in `.mcp.json`
422	2. Install plugin locally (`.claude-plugin/`)
423	3. Run `/mcp` to verify server appears
424	4. Test tool calls in commands
425	5. Check `claude --debug` logs for connection issues
426
427	### Validation Checklist
428
429	- [ ] MCP configuration is valid JSON
430	- [ ] Server URL is correct and accessible
431	- [ ] Required environment variables documented
432	- [ ] Tools appear in `/mcp` output
433	- [ ] Authentication works (OAuth or tokens)
434	- [ ] Tool calls succeed from commands
435	- [ ] Error cases handled gracefully
436
437	## Debugging
438
439	### Enable Debug Logging
440
441	```bash
442	claude --debug
443	```
444
445	Look for:
446	- MCP server connection attempts
447	- Tool discovery logs
448	- Authentication flows
449	- Tool call errors
450
451	### Common Issues
452
453	Server not connecting:
454	- Check URL is correct
455	- Verify server is running (stdio)
456	- Check network connectivity
457	- Review authentication configuration
458
459	Tools not available:
460	- Verify server connected successfully
461	- Check tool names match exactly
462	- Run `/mcp` to see available tools
463	- Restart Claude Code after config changes
464
465	Authentication failing:
466	- Clear cached auth tokens
467	- Re-authenticate
468	- Check token scopes and permissions
469	- Verify environment variables set
470
471	## Quick Reference
472
473	### MCP Server Types
474
475	\| Type \| Transport \| Best For \| Auth \|
476	\|------\|-----------\|----------\|------\|
477	\| stdio \| Process \| Local tools, custom servers \| Env vars \|
478	\| SSE \| HTTP \| Hosted services, cloud APIs \| OAuth \|
479	\| HTTP \| REST \| API backends, token auth \| Tokens \|
480	\| ws \| WebSocket \| Real-time, streaming \| Tokens \|
481
482	### Configuration Checklist
483
484	- [ ] Server type specified (stdio/SSE/HTTP/ws)
485	- [ ] Type-specific fields complete (command or url)
486	- [ ] Authentication configured
487	- [ ] Environment variables documented
488	- [ ] HTTPS/WSS used (not HTTP/WS)
489	- [ ] ${CLAUDE_PLUGIN_ROOT} used for paths
490
491	### Best Practices
492
493	DO:
494	- ✅ Use ${CLAUDE_PLUGIN_ROOT} for portable paths
495	- ✅ Document required environment variables
496	- ✅ Use secure connections (HTTPS/WSS)
497	- ✅ Pre-allow specific MCP tools in commands
498	- ✅ Test MCP integration before publishing
499	- ✅ Handle connection and tool errors gracefully
500
501	DON'T:
502	- ❌ Hardcode absolute paths
503	- ❌ Commit credentials to git
504	- ❌ Use HTTP instead of HTTPS
505	- ❌ Pre-allow all tools with wildcards
506	- ❌ Skip error handling
507	- ❌ Forget to document setup
508
509	## Additional Resources
510
511	### Reference Files
512
513	For detailed information, consult:
514
515	- `references/server-types.md` - Deep dive on each server type
516	- `references/authentication.md` - Authentication patterns and OAuth
517	- `references/tool-usage.md` - Using MCP tools in commands and agents
518
519	### Example Configurations
520
521	Working examples in `examples/`:
522
523	- `stdio-server.json` - Local stdio MCP server
524	- `sse-server.json` - Hosted SSE server with OAuth
525	- `http-server.json` - REST API with token auth
526
527	### External Resources
528
529	- Official MCP Docs: https://modelcontextprotocol.io/
530	- Claude Code MCP Docs: https://docs.claude.com/en/docs/claude-code/mcp
531	- MCP SDK: @modelcontextprotocol/sdk
532	- Testing: Use `claude --debug` and `/mcp` command
533
534	## Implementation Workflow
535
536	To add MCP integration to a plugin:
537
538	1. Choose MCP server type (stdio, SSE, HTTP, ws)
539	2. Create `.mcp.json` at plugin root with configuration
540	3. Use ${CLAUDE_PLUGIN_ROOT} for all file references
541	4. Document required environment variables in README
542	5. Test locally with `/mcp` command
543	6. Pre-allow MCP tools in relevant commands
544	7. Handle authentication (OAuth or tokens)
545	8. Test error cases (connection failures, auth errors)
546	9. Document MCP integration in plugin README
547
548	Focus on stdio for custom/local servers, SSE for hosted services with OAuth.

6 picks

Type

Run `npx skills use "https://github.com/anthropics/claude-code" --skill "anthropics/claude-code/mcp-integration"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/anthropics/claude-code" that are relevant to the current task. Run `npx skills add "https://github.com/anthropics/claude-code"` and select the relevant skills, then follow their instructions.

mcp-integration

How to install mcp-integration?

Related

mcp-integration

How to install mcp-integration?

Related