surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / plugins / plugin-dev / skills / mcp-integration / references / tool-usage.md

Daisy S. HollmanMerge pull request #11780 from anthropics/daisy/plugin-dev/public-marketplace c508e59 · on Nov 18, 2025 History

538 lines · 11.4 KBPreview CodeRaw

1	# Using MCP Tools in Commands and Agents
2
3	Complete guide to using MCP tools effectively in Claude Code plugin commands and agents.
4
5	## Overview
6
7	Once an MCP server is configured, its tools become available with the prefix `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`. Use these tools in commands and agents just like built-in Claude Code tools.
8
9	## Tool Naming Convention
10
11	### Format
12
13	```
14	mcp__plugin_<plugin-name>_<server-name>__<tool-name>
15	```
16
17	### Examples
18
19	Asana plugin with asana server:
20	- `mcp__plugin_asana_asana__asana_create_task`
21	- `mcp__plugin_asana_asana__asana_search_tasks`
22	- `mcp__plugin_asana_asana__asana_get_project`
23
24	Custom plugin with database server:
25	- `mcp__plugin_myplug_database__query`
26	- `mcp__plugin_myplug_database__execute`
27	- `mcp__plugin_myplug_database__list_tables`
28
29	### Discovering Tool Names
30
31	Use `/mcp` command:
32	```bash
33	/mcp
34	```
35
36	This shows:
37	- All available MCP servers
38	- Tools provided by each server
39	- Tool schemas and descriptions
40	- Full tool names for use in configuration
41
42	## Using Tools in Commands
43
44	### Pre-Allowing Tools
45
46	Specify MCP tools in command frontmatter:
47
48	```markdown
49	---
50	description: Create a new Asana task
51	allowed-tools: [
52	"mcp__plugin_asana_asana__asana_create_task"
53	]
54	---
55
56	# Create Task Command
57
58	To create a task:
59	1. Gather task details from user
60	2. Use mcp__plugin_asana_asana__asana_create_task with the details
61	3. Confirm creation to user
62	```
63
64	### Multiple Tools
65
66	```markdown
67	---
68	allowed-tools: [
69	"mcp__plugin_asana_asana__asana_create_task",
70	"mcp__plugin_asana_asana__asana_search_tasks",
71	"mcp__plugin_asana_asana__asana_get_project"
72	]
73	---
74	```
75
76	### Wildcard (Use Sparingly)
77
78	```markdown
79	---
80	allowed-tools: ["mcp__plugin_asana_asana__*"]
81	---
82	```
83
84	Caution: Only use wildcards if the command truly needs access to all tools from a server.
85
86	### Tool Usage in Command Instructions
87
88	Example command:
89	```markdown
90	---
91	description: Search and create Asana tasks
92	allowed-tools: [
93	"mcp__plugin_asana_asana__asana_search_tasks",
94	"mcp__plugin_asana_asana__asana_create_task"
95	]
96	---
97
98	# Asana Task Management
99
100	## Searching Tasks
101
102	To search for tasks:
103	1. Use mcp__plugin_asana_asana__asana_search_tasks
104	2. Provide search filters (assignee, project, etc.)
105	3. Display results to user
106
107	## Creating Tasks
108
109	To create a task:
110	1. Gather task details:
111	- Title (required)
112	- Description
113	- Project
114	- Assignee
115	- Due date
116	2. Use mcp__plugin_asana_asana__asana_create_task
117	3. Show confirmation with task link
118	```
119
120	## Using Tools in Agents
121
122	### Agent Configuration
123
124	Agents can use MCP tools autonomously without pre-allowing them:
125
126	```markdown
127	---
128	name: asana-status-updater
129	description: This agent should be used when the user asks to "update Asana status", "generate project report", or "sync Asana tasks"
130	model: inherit
131	color: blue
132	---
133
134	## Role
135
136	Autonomous agent for generating Asana project status reports.
137
138	## Process
139
140	1. Query tasks: Use mcp__plugin_asana_asana__asana_search_tasks to get all tasks
141	2. Analyze progress: Calculate completion rates and identify blockers
142	3. Generate report: Create formatted status update
143	4. Update Asana: Use mcp__plugin_asana_asana__asana_create_comment to post report
144
145	## Available Tools
146
147	The agent has access to all Asana MCP tools without pre-approval.
148	```
149
150	### Agent Tool Access
151
152	Agents have broader tool access than commands:
153	- Can use any tool Claude determines is necessary
154	- Don't need pre-allowed lists
155	- Should document which tools they typically use
156
157	## Tool Call Patterns
158
159	### Pattern 1: Simple Tool Call
160
161	Single tool call with validation:
162
163	```markdown
164	Steps:
165	1. Validate user provided required fields
166	2. Call mcp__plugin_api_server__create_item with validated data
167	3. Check for errors
168	4. Display confirmation
169	```
170
171	### Pattern 2: Sequential Tools
172
173	Chain multiple tool calls:
174
175	```markdown
176	Steps:
177	1. Search for existing items: mcp__plugin_api_server__search
178	2. If not found, create new: mcp__plugin_api_server__create
179	3. Add metadata: mcp__plugin_api_server__update_metadata
180	4. Return final item ID
181	```
182
183	### Pattern 3: Batch Operations
184
185	Multiple calls with same tool:
186
187	```markdown
188	Steps:
189	1. Get list of items to process
190	2. For each item:
191	- Call mcp__plugin_api_server__update_item
192	- Track success/failure
193	3. Report results summary
194	```
195
196	### Pattern 4: Error Handling
197
198	Graceful error handling:
199
200	```markdown
201	Steps:
202	1. Try to call mcp__plugin_api_server__get_data
203	2. If error (rate limit, network, etc.):
204	- Wait and retry (max 3 attempts)
205	- If still failing, inform user
206	- Suggest checking configuration
207	3. On success, process data
208	```
209
210	## Tool Parameters
211
212	### Understanding Tool Schemas
213
214	Each MCP tool has a schema defining its parameters. View with `/mcp`.
215
216	Example schema:
217	```json
218	{
219	"name": "asana_create_task",
220	"description": "Create a new Asana task",
221	"inputSchema": {
222	"type": "object",
223	"properties": {
224	"name": {
225	"type": "string",
226	"description": "Task title"
227	},
228	"notes": {
229	"type": "string",
230	"description": "Task description"
231	},
232	"workspace": {
233	"type": "string",
234	"description": "Workspace GID"
235	}
236	},
237	"required": ["name", "workspace"]
238	}
239	}
240	```
241
242	### Calling Tools with Parameters
243
244	Claude automatically structures tool calls based on schema:
245
246	```typescript
247	// Claude generates this internally
248	{
249	toolName: "mcp__plugin_asana_asana__asana_create_task",
250	input: {
251	name: "Review PR #123",
252	notes: "Code review for new feature",
253	workspace: "12345",
254	assignee: "67890",
255	due_on: "2025-01-15"
256	}
257	}
258	```
259
260	### Parameter Validation
261
262	In commands, validate before calling:
263
264	```markdown
265	Steps:
266	1. Check required parameters:
267	- Title is not empty
268	- Workspace ID is provided
269	- Due date is valid format (YYYY-MM-DD)
270	2. If validation fails, ask user to provide missing data
271	3. If validation passes, call MCP tool
272	4. Handle tool errors gracefully
273	```
274
275	## Response Handling
276
277	### Success Responses
278
279	```markdown
280	Steps:
281	1. Call MCP tool
282	2. On success:
283	- Extract relevant data from response
284	- Format for user display
285	- Provide confirmation message
286	- Include relevant links or IDs
287	```
288
289	### Error Responses
290
291	```markdown
292	Steps:
293	1. Call MCP tool
294	2. On error:
295	- Check error type (auth, rate limit, validation, etc.)
296	- Provide helpful error message
297	- Suggest remediation steps
298	- Don't expose internal error details to user
299	```
300
301	### Partial Success
302
303	```markdown
304	Steps:
305	1. Batch operation with multiple MCP calls
306	2. Track successes and failures separately
307	3. Report summary:
308	- "Successfully processed 8 of 10 items"
309	- "Failed items: [item1, item2] due to [reason]"
310	- Suggest retry or manual intervention
311	```
312
313	## Performance Optimization
314
315	### Batching Requests
316
317	Good: Single query with filters
318	```markdown
319	Steps:
320	1. Call mcp__plugin_api_server__search with filters:
321	- project_id: "123"
322	- status: "active"
323	- limit: 100
324	2. Process all results
325	```
326
327	Avoid: Many individual queries
328	```markdown
329	Steps:
330	1. For each item ID:
331	- Call mcp__plugin_api_server__get_item
332	- Process item
333	```
334
335	### Caching Results
336
337	```markdown
338	Steps:
339	1. Call expensive MCP operation: mcp__plugin_api_server__analyze
340	2. Store results in variable for reuse
341	3. Use cached results for subsequent operations
342	4. Only re-fetch if data changes
343	```
344
345	### Parallel Tool Calls
346
347	When tools don't depend on each other, call in parallel:
348
349	```markdown
350	Steps:
351	1. Make parallel calls (Claude handles this automatically):
352	- mcp__plugin_api_server__get_project
353	- mcp__plugin_api_server__get_users
354	- mcp__plugin_api_server__get_tags
355	2. Wait for all to complete
356	3. Combine results
357	```
358
359	## Integration Best Practices
360
361	### User Experience
362
363	Provide feedback:
364	```markdown
365	Steps:
366	1. Inform user: "Searching Asana tasks..."
367	2. Call mcp__plugin_asana_asana__asana_search_tasks
368	3. Show progress: "Found 15 tasks, analyzing..."
369	4. Present results
370	```
371
372	Handle long operations:
373	```markdown
374	Steps:
375	1. Warn user: "This may take a minute..."
376	2. Break into smaller steps with updates
377	3. Show incremental progress
378	4. Final summary when complete
379	```
380
381	### Error Messages
382
383	Good error messages:
384	```
385	❌ "Could not create task. Please check:
386	1. You're logged into Asana
387	2. You have access to workspace 'Engineering'
388	3. The project 'Q1 Goals' exists"
389	```
390
391	Poor error messages:
392	```
393	❌ "Error: MCP tool returned 403"
394	```
395
396	### Documentation
397
398	Document MCP tool usage in command:
399	```markdown
400	## MCP Tools Used
401
402	This command uses the following Asana MCP tools:
403	- asana_search_tasks: Search for tasks matching criteria
404	- asana_create_task: Create new task with details
405	- asana_update_task: Update existing task properties
406
407	Ensure you're authenticated to Asana before running this command.
408	```
409
410	## Testing Tool Usage
411
412	### Local Testing
413
414	1. Configure MCP server in `.mcp.json`
415	2. Install plugin locally in `.claude-plugin/`
416	3. Verify tools available with `/mcp`
417	4. Test command that uses tools
418	5. Check debug output: `claude --debug`
419
420	### Test Scenarios
421
422	Test successful calls:
423	```markdown
424	Steps:
425	1. Create test data in external service
426	2. Run command that queries this data
427	3. Verify correct results returned
428	```
429
430	Test error cases:
431	```markdown
432	Steps:
433	1. Test with missing authentication
434	2. Test with invalid parameters
435	3. Test with non-existent resources
436	4. Verify graceful error handling
437	```
438
439	Test edge cases:
440	```markdown
441	Steps:
442	1. Test with empty results
443	2. Test with maximum results
444	3. Test with special characters
445	4. Test with concurrent access
446	```
447
448	## Common Patterns
449
450	### Pattern: CRUD Operations
451
452	```markdown
453	---
454	allowed-tools: [
455	"mcp__plugin_api_server__create_item",
456	"mcp__plugin_api_server__read_item",
457	"mcp__plugin_api_server__update_item",
458	"mcp__plugin_api_server__delete_item"
459	]
460	---
461
462	# Item Management
463
464	## Create
465	Use create_item with required fields...
466
467	## Read
468	Use read_item with item ID...
469
470	## Update
471	Use update_item with item ID and changes...
472
473	## Delete
474	Use delete_item with item ID (ask for confirmation first)...
475	```
476
477	### Pattern: Search and Process
478
479	```markdown
480	Steps:
481	1. Search: mcp__plugin_api_server__search with filters
482	2. Filter: Apply additional local filtering if needed
483	3. Transform: Process each result
484	4. Present: Format and display to user
485	```
486
487	### Pattern: Multi-Step Workflow
488
489	```markdown
490	Steps:
491	1. Setup: Gather all required information
492	2. Validate: Check data completeness
493	3. Execute: Chain of MCP tool calls:
494	- Create parent resource
495	- Create child resources
496	- Link resources together
497	- Add metadata
498	4. Verify: Confirm all steps succeeded
499	5. Report: Provide summary to user
500	```
501
502	## Troubleshooting
503
504	### Tools Not Available
505
506	Check:
507	- MCP server configured correctly
508	- Server connected (check `/mcp`)
509	- Tool names match exactly (case-sensitive)
510	- Restart Claude Code after config changes
511
512	### Tool Calls Failing
513
514	Check:
515	- Authentication is valid
516	- Parameters match tool schema
517	- Required parameters provided
518	- Check `claude --debug` logs
519
520	### Performance Issues
521
522	Check:
523	- Batching queries instead of individual calls
524	- Caching results when appropriate
525	- Not making unnecessary tool calls
526	- Parallel calls when possible
527
528	## Conclusion
529
530	Effective MCP tool usage requires:
531	1. Understanding tool schemas via `/mcp`
532	2. Pre-allowing tools in commands appropriately
533	3. Handling errors gracefully
534	4. Optimizing performance with batching and caching
535	5. Providing good UX with feedback and clear errors
536	6. Testing thoroughly before deployment
537
538	Follow these patterns for robust MCP tool integration in your plugin commands and agents.