tools-only Using MCP Tools in Commands and Agents
Complete guide to using MCP tools effectively in Claude Code plugin commands and agents.
Overview
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.
Tool Naming Convention
Format
mcp__plugin_<plugin-name>_<server-name>__<tool-name>
Examples
Asana plugin with asana server:
mcp__plugin_asana_asana__asana_create_taskmcp__plugin_asana_asana__asana_search_tasksmcp__plugin_asana_asana__asana_get_project
Custom plugin with database server:
mcp__plugin_myplug_database__querymcp__plugin_myplug_database__executemcp__plugin_myplug_database__list_tables
Discovering Tool Names
Use /mcp command:
/mcp
This shows:
- All available MCP servers
- Tools provided by each server
- Tool schemas and descriptions
- Full tool names for use in configuration
Using Tools in Commands
Pre-Allowing Tools
Specify MCP tools in command frontmatter:
---
description: Create a new Asana task
allowed-tools: [
"mcp__plugin_asana_asana__asana_create_task"
]
---
# Create Task Command
To create a task:
1. Gather task details from user
2. Use mcp__plugin_asana_asana__asana_create_task with the details
3. Confirm creation to user
Multiple Tools
---
allowed-tools: [
"mcp__plugin_asana_asana__asana_create_task",
"mcp__plugin_asana_asana__asana_search_tasks",
"mcp__plugin_asana_asana__asana_get_project"
]
---
Wildcard (Use Sparingly)
---
allowed-tools: ["mcp__plugin_asana_asana__*"]
---
Caution: Only use wildcards if the command truly needs access to all tools from a server.
Tool Usage in Command Instructions
Example command:
---
description: Search and create Asana tasks
allowed-tools: [
"mcp__plugin_asana_asana__asana_search_tasks",
"mcp__plugin_asana_asana__asana_create_task"
]
---
# Asana Task Management
## Searching Tasks
To search for tasks:
1. Use mcp__plugin_asana_asana__asana_search_tasks
2. Provide search filters (assignee, project, etc.)
3. Display results to user
## Creating Tasks
To create a task:
1. Gather task details:
- Title (required)
- Description
- Project
- Assignee
- Due date
2. Use mcp__plugin_asana_asana__asana_create_task
3. Show confirmation with task link
Using Tools in Agents
Agent Configuration
Agents can use MCP tools autonomously without pre-allowing them:
---
name: asana-status-updater
description: This agent should be used when the user asks to "update Asana status", "generate project report", or "sync Asana tasks"
model: inherit
color: blue
---
## Role
Autonomous agent for generating Asana project status reports.
## Process
1. **Query tasks**: Use mcp__plugin_asana_asana__asana_search_tasks to get all tasks
2. **Analyze progress**: Calculate completion rates and identify blockers
3. **Generate report**: Create formatted status update
4. **Update Asana**: Use mcp__plugin_asana_asana__asana_create_comment to post report
## Available Tools
The agent has access to all Asana MCP tools without pre-approval.
Agent Tool Access
Agents have broader tool access than commands:
- Can use any tool Claude determines is necessary
- Don't need pre-allowed lists
- Should document which tools they typically use
Tool Call Patterns
Pattern 1: Simple Tool Call
Single tool call with validation:
Steps:
1. Validate user provided required fields
2. Call mcp__plugin_api_server__create_item with validated data
3. Check for errors
4. Display confirmation
Pattern 2: Sequential Tools
Chain multiple tool calls:
Steps:
1. Search for existing items: mcp__plugin_api_server__search
2. If not found, create new: mcp__plugin_api_server__create
3. Add metadata: mcp__plugin_api_server__update_metadata
4. Return final item ID
Pattern 3: Batch Operations
Multiple calls with same tool:
Steps:
1. Get list of items to process
2. For each item:
- Call mcp__plugin_api_server__update_item
- Track success/failure
3. Report results summary
Pattern 4: Error Handling
Graceful error handling:
Steps:
1. Try to call mcp__plugin_api_server__get_data
2. If error (rate limit, network, etc.):
- Wait and retry (max 3 attempts)
- If still failing, inform user
- Suggest checking configuration
3. On success, process data
Tool Parameters
Understanding Tool Schemas
Each MCP tool has a schema defining its parameters. View with /mcp.
Example schema:
{
"name": "asana_create_task",
"description": "Create a new Asana task",
"inputSchema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Task title"
},
"notes": {
"type": "string",
"description": "Task description"
},
"workspace": {
"type": "string",
"description": "Workspace GID"
}
},
"required": ["name", "workspace"]
}
}
Calling Tools with Parameters
Claude automatically structures tool calls based on schema:
// Claude generates this internally
{
toolName: "mcp__plugin_asana_asana__asana_create_task",
input: {
name: "Review PR #123",
notes: "Code review for new feature",
workspace: "12345",
assignee: "67890",
due_on: "2025-01-15"
}
}
Parameter Validation
In commands, validate before calling:
Steps:
1. Check required parameters:
- Title is not empty
- Workspace ID is provided
- Due date is valid format (YYYY-MM-DD)
2. If validation fails, ask user to provide missing data
3. If validation passes, call MCP tool
4. Handle tool errors gracefully
Response Handling
Success Responses
Steps:
1. Call MCP tool
2. On success:
- Extract relevant data from response
- Format for user display
- Provide confirmation message
- Include relevant links or IDs
Error Responses
Steps:
1. Call MCP tool
2. On error:
- Check error type (auth, rate limit, validation, etc.)
- Provide helpful error message
- Suggest remediation steps
- Don't expose internal error details to user
Partial Success
Steps:
1. Batch operation with multiple MCP calls
2. Track successes and failures separately
3. Report summary:
- "Successfully processed 8 of 10 items"
- "Failed items: [item1, item2] due to [reason]"
- Suggest retry or manual intervention
Performance Optimization
Batching Requests
Good: Single query with filters
Steps:
1. Call mcp__plugin_api_server__search with filters:
- project_id: "123"
- status: "active"
- limit: 100
2. Process all results
Avoid: Many individual queries
Steps:
1. For each item ID:
- Call mcp__plugin_api_server__get_item
- Process item
Caching Results
Steps:
1. Call expensive MCP operation: mcp__plugin_api_server__analyze
2. Store results in variable for reuse
3. Use cached results for subsequent operations
4. Only re-fetch if data changes
Parallel Tool Calls
When tools don't depend on each other, call in parallel:
Steps:
1. Make parallel calls (Claude handles this automatically):
- mcp__plugin_api_server__get_project
- mcp__plugin_api_server__get_users
- mcp__plugin_api_server__get_tags
2. Wait for all to complete
3. Combine results
Integration Best Practices
User Experience
Provide feedback:
Steps:
1. Inform user: "Searching Asana tasks..."
2. Call mcp__plugin_asana_asana__asana_search_tasks
3. Show progress: "Found 15 tasks, analyzing..."
4. Present results
Handle long operations:
Steps:
1. Warn user: "This may take a minute..."
2. Break into smaller steps with updates
3. Show incremental progress
4. Final summary when complete
Error Messages
Good error messages:
❌ "Could not create task. Please check:
1. You're logged into Asana
2. You have access to workspace 'Engineering'
3. The project 'Q1 Goals' exists"
Poor error messages:
❌ "Error: MCP tool returned 403"
Documentation
Document MCP tool usage in command:
## MCP Tools Used
This command uses the following Asana MCP tools:
- **asana_search_tasks**: Search for tasks matching criteria
- **asana_create_task**: Create new task with details
- **asana_update_task**: Update existing task properties
Ensure you're authenticated to Asana before running this command.
Testing Tool Usage
Local Testing
- Configure MCP server in
.mcp.json - Install plugin locally in
.claude-plugin/ - Verify tools available with
/mcp - Test command that uses tools
- Check debug output:
claude --debug
Test Scenarios
Test successful calls:
Steps:
1. Create test data in external service
2. Run command that queries this data
3. Verify correct results returned
Test error cases:
Steps:
1. Test with missing authentication
2. Test with invalid parameters
3. Test with non-existent resources
4. Verify graceful error handling
Test edge cases:
Steps:
1. Test with empty results
2. Test with maximum results
3. Test with special characters
4. Test with concurrent access
Common Patterns
Pattern: CRUD Operations
---
allowed-tools: [
"mcp__plugin_api_server__create_item",
"mcp__plugin_api_server__read_item",
"mcp__plugin_api_server__update_item",
"mcp__plugin_api_server__delete_item"
]
---
# Item Management
## Create
Use create_item with required fields...
## Read
Use read_item with item ID...
## Update
Use update_item with item ID and changes...
## Delete
Use delete_item with item ID (ask for confirmation first)...
Pattern: Search and Process
Steps:
1. **Search**: mcp__plugin_api_server__search with filters
2. **Filter**: Apply additional local filtering if needed
3. **Transform**: Process each result
4. **Present**: Format and display to user
Pattern: Multi-Step Workflow
Steps:
1. **Setup**: Gather all required information
2. **Validate**: Check data completeness
3. **Execute**: Chain of MCP tool calls:
- Create parent resource
- Create child resources
- Link resources together
- Add metadata
4. **Verify**: Confirm all steps succeeded
5. **Report**: Provide summary to user
Troubleshooting
Tools Not Available
Check:
- MCP server configured correctly
- Server connected (check
/mcp) - Tool names match exactly (case-sensitive)
- Restart Claude Code after config changes
Tool Calls Failing
Check:
- Authentication is valid
- Parameters match tool schema
- Required parameters provided
- Check
claude --debuglogs
Performance Issues
Check:
- Batching queries instead of individual calls
- Caching results when appropriate
- Not making unnecessary tool calls
- Parallel calls when possible
Conclusion
Effective MCP tool usage requires:
- Understanding tool schemas via
/mcp - Pre-allowing tools in commands appropriately
- Handling errors gracefully
- Optimizing performance with batching and caching
- Providing good UX with feedback and clear errors
- Testing thoroughly before deployment
Follow these patterns for robust MCP tool integration in your plugin commands and agents.