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

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_task
• mcp__plugin_asana_asana__asana_search_tasks
• mcp__plugin_asana_asana__asana_get_project

Custom plugin with database server:

• mcp__plugin_myplug_database__query
• mcp__plugin_myplug_database__execute
• mcp__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

1. Configure MCP server in .mcp.json
2. Install plugin locally in .claude-plugin/
3. Verify tools available with /mcp
4. Test command that uses tools
5. 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 --debug logs

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:

1. Understanding tool schemas via /mcp
2. Pre-allowing tools in commands appropriately
3. Handling errors gracefully
4. Optimizing performance with batching and caching
5. Providing good UX with feedback and clear errors
6. Testing thoroughly before deployment

Follow these patterns for robust MCP tool integration in your plugin commands and agents.