MCP Tools Reference

Complete reference documentation for all available MCP tools in n8n MCP Bridge.

Tool Overview

MCP tools enable AI assistants to interact with your n8n workflows through standardized function calls.

Available Now

Currently implemented tools:

• ping_n8n - Test n8n instance connectivity

Coming Soon

Tools in development:

• execute_workflow - Execute workflows by ID or name
• list_workflows - List all available workflows
• get_workflow_status - Check workflow execution status
• search_nodes - Search through 525+ n8n nodes
• get_node_details - Get detailed node information

Tool Categories

Diagnostics

Tools for testing and troubleshooting:

Tool	Status	Description
ping_n8n	✅ Available	Test n8n connectivity

Workflow Management

Tools for managing workflows:

Tool	Status	Description
execute_workflow	📋 Planned	Execute a workflow
list_workflows	📋 Planned	List all workflows
get_workflow_status	📋 Planned	Check execution status
cancel_workflow	📋 Planned	Cancel running workflow

Node Discovery

Tools for exploring n8n nodes:

Tool	Status	Description
search_nodes	📋 Planned	Search available nodes
get_node_details	📋 Planned	Get node documentation
list_node_categories	📋 Planned	List node categories

Credentials (Future)

Tools for credential management:

Tool	Status	Description
list_credentials	🔮 Future	List available credentials
test_credential	🔮 Future	Test credential validity

Tool Structure

All tools follow this structure:

Request

{
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "param1": "value1",
      "param2": "value2"
    }
  }
}

Response

{
  "success": true,
  "message": "Operation completed",
  "data": {}
}

Error

{
  "success": false,
  "error": "Error message",
  "details": "Additional information"
}

Using Tools

Natural Language

Ask AI assistants naturally:

Can you check if my n8n instance is working?

The AI will automatically select and call the appropriate tool (ping_n8n).

Direct API Call

Call tools directly via MCP:

import { MCPClient } from '@modelcontextprotocol/sdk'

const client = new MCPClient({
  url: 'http://localhost:3001/mcp?apiKey=mcp_your_key',
})

const result = await client.callTool({
  name: 'ping_n8n',
  arguments: {},
})

console.log(result)

Via HTTP

Make direct HTTP requests:

curl -X POST http://localhost:3001/mcp?apiKey=mcp_your_key \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "ping_n8n",
      "arguments": {}
    }
  }'

Tool Parameters

Parameter Types

Tools accept various parameter types:

{
  string: "text value",
  number: 42,
  boolean: true,
  array: ["item1", "item2"],
  object: { key: "value" }
}

Required vs Optional

Parameters can be:

• Required: Must be provided
• Optional: Can be omitted (default used)

Example:

{
  workflowId: "5",           // Required
  parameters: { ... },       // Optional
  waitForCompletion: true    // Optional (default: false)
}

Parameter Validation

All parameters are validated:

• Type checking
• Range validation
• Format verification
• Required field checking

Invalid parameters result in error:

{
  "success": false,
  "error": "Invalid parameter",
  "details": "workflowId must be a non-empty string"
}

Tool Responses

Success Response

{
  "success": true,
  "message": "Workflow executed successfully",
  "data": {
    "executionId": "exec_abc123",
    "startedAt": "2024-01-15T10:30:00Z",
    "result": {}
  }
}

Partial Success

Some operations may partially succeed:

{
  "success": true,
  "message": "3 of 5 workflows executed",
  "data": {
    "successful": ["wf1", "wf2", "wf3"],
    "failed": ["wf4", "wf5"],
    "errors": {
      "wf4": "Timeout",
      "wf5": "Invalid parameters"
    }
  }
}

Error Response

{
  "success": false,
  "error": "n8n connection failed",
  "details": "Could not connect to https://n8n.example.com",
  "retryable": true,
  "errorCode": "CONNECTION_FAILED"
}

Tool Permissions

API Key Permissions

Each API key has access to specific tools based on its configuration.

OAuth Scopes (Future)

OAuth clients will use scopes for tool access:

• n8n:read - Read-only tools (list, get)
• n8n:execute - Execute workflows
• n8n:admin - Administrative tools

Tool Development

Adding Custom Tools

To add a new tool:

1. Create tool definition in packages/mcp-server/src/tools/
2. Implement tool handler
3. Register tool in tool registry
4. Add tests
5. Update documentation

Example:

// packages/mcp-server/src/tools/my-tool.ts

export const myTool = {
  name: 'my_custom_tool',
  description: 'Does something useful',
  parameters: {
    type: 'object',
    properties: {
      input: {
        type: 'string',
        description: 'Input parameter',
      },
    },
    required: ['input'],
  },
  handler: async (params, context) => {
    try {
      // Tool implementation
      const result = await doSomething(params.input)

      return {
        success: true,
        data: result,
      }
    } catch (error) {
      return {
        success: false,
        error: error.message,
      }
    }
  },
}

Tool Testing

Test tools thoroughly:

import { describe, it, expect } from 'vitest'
import { myTool } from './my-tool'

describe('myTool', () => {
  it('should execute successfully', async () => {
    const result = await myTool.handler({ input: 'test' })
    expect(result.success).toBe(true)
  })

  it('should handle errors', async () => {
    const result = await myTool.handler({ input: '' })
    expect(result.success).toBe(false)
  })
})

Best Practices

Tool Design

• Single responsibility: Each tool does one thing well
• Clear naming: Use descriptive, action-oriented names
• Consistent interface: Follow standard request/response format
• Good documentation: Provide examples and error descriptions

Error Handling

• Descriptive errors: Explain what went wrong
• Actionable messages: Tell users how to fix issues
• Error codes: Use consistent error codes
• Retry guidance: Indicate if operation is retryable

Performance

• Fast responses: Keep tool execution under 5 seconds
• Async operations: Use async/await for I/O
• Timeout handling: Set reasonable timeouts
• Resource cleanup: Clean up resources properly

Monitoring

Tool Analytics

Track tool usage:

• Call count per tool
• Success/failure rates
• Average execution time
• Error distribution

Performance Metrics

Monitor performance:

• Response time percentiles (p50, p95, p99)
• Timeout rate
• Error rate by type
• Throughput (calls per minute)

Troubleshooting

Tool Not Available

If a tool isn't available:

1. Check tool is in current release
2. Verify API key has access
3. Ensure MCP server is running
4. Check tool name spelling

Tool Execution Failed

If tool fails:

1. Review error message
2. Check parameter values
3. Verify n8n connectivity
4. Check server logs

Slow Tool Response

If tool is slow:

1. Check n8n performance
2. Verify network latency
3. Review workflow complexity
4. Monitor server resources

Tool Reference

Browse detailed documentation for each tool:

• ping_n8n →

More tools coming soon!

Contributing

Help us add more tools:

1. Open an issue with tool proposal
2. Fork the repository
3. Implement the tool
4. Submit a pull request
5. Update documentation

Next Steps

• View ping_n8n Tool →
• Learn About Features →
• Read API Reference →