MCP Tool Reference

This comprehensive reference documents all available MCP tools in Consultia, organized by category. Each tool includes detailed usage instructions and example results.

Tool Categories

1. Core MCP Tools

These are the fundamental MCP protocol tools that enable tool discovery and execution.

2. Consultia Data Access Tools

Tools for querying and retrieving Consultia data with various filtering and analysis capabilities.

3. Business Intelligence Tools

Advanced analytics and business intelligence tools for data analysis and insights.

4. Business Operations Tools

Tools for executing business operations and automated workflows.

Core MCP Tools

list_tools

What it does:
Discovers and lists all available MCP tools in the Consultia system, providing detailed information about each tool's capabilities, required permissions, and usage.

How to use it:

{
  "method": "tools/list"
}

Example result:

{
  "tools": [
    {
      "name": "list_tools",
      "description": "List all available MCP tools and their capabilities",
      "inputSchema": {},
      "requiredPermissions": []
    },
    {
      "name": "call_tool",
      "description": "Execute a specific MCP tool with parameters",
      "inputSchema": {
        "name": "string",
        "arguments": "object"
      },
      "requiredPermissions": []
    },
    {
      "name": "query_crm_data",
      "description": "Query Consultia data including customers, invoices, payments, and more",
      "inputSchema": {
        "entity": "string",
        "filters": "object",
        "limit": "number"
      },
      "requiredPermissions": ["READ_CUSTOMERS", "READ_INVOICES", "READ_PAYMENTS"]
    }
  ]
}

call_tool

What it does:
Executes a specific MCP tool with provided parameters. This is the primary method for invoking any tool in the system.

How to use it:

{
  "method": "tools/call",
  "params": {
    "name": "query_crm_data",
    "arguments": {
      "entity": "customers",
      "filters": {
        "isArchived": false
      },
      "limit": 10
    }
  }
}

Example result:

{
  "content": [
    {
      "type": "text",
      "text": "Successfully executed query_crm_data tool"
    }
  ],
  "toolResults": [
    {
      "name": "query_crm_data",
      "result": {
        "success": true,
        "data": [
          {
            "id": 1,
            "name": "Acme Corporation",
            "email": "contact@acme.com",
            "phone": "+1-555-0123",
            "isArchived": false,
            "createdAt": "2024-01-15T10:30:00Z"
          }
        ],
        "count": 1,
        "execution_time_ms": 45
      }
    }
  ]
}

Consultia Data Access Tools

query_crm_data

What it does:
Queries Consultia data across multiple entities including customers, invoices, payments, resources, and products. Supports advanced filtering, sorting, and pagination.

How to use it:

{
  "method": "tools/call",
  "params": {
    "name": "query_crm_data",
    "arguments": {
      "entity": "customers",
      "filters": {
        "isArchived": false,
        "createdAt": {
          "gte": "2024-01-01T00:00:00Z"
        }
      },
      "sort": {
        "field": "name",
        "order": "asc"
      },
      "limit": 20,
      "offset": 0
    }
  }
}

Supported entities:

customers - Customer information and relationships
invoices - Invoice data and status
payments - Payment records and history
resources - Resource allocation and worksheets
products - Product catalog and pricing

Example result:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Acme Corporation",
      "email": "contact@acme.com",
      "phone": "+1-555-0123",
      "address": "123 Business St, City, State 12345",
      "isArchived": false,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:22:00Z",
      "purchaseOrders": [
        {
          "id": 101,
          "orderNumber": "PO-2024-001",
          "status": "ACTIVE",
          "totalAmount": 15000.00
        }
      ]
    }
  ],
  "count": 1,
  "total": 1,
  "execution_time_ms": 67
}

Business Intelligence Tools

get_crm_analytics

What it does:
Provides comprehensive business intelligence and analytics across all Consultia entities. Supports various metrics, time ranges, and grouping options for detailed analysis.

How to use it:

{
  "method": "tools/call",
  "params": {
    "name": "get_crm_analytics",
    "arguments": {
      "metric": "customer_count",
      "timeRange": {
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-12-31T23:59:59Z",
        "period": "month"
      },
      "groupBy": "month",
      "limit": 50
    }
  }
}

Available metrics:

customer_count - Total number of customers
invoice_total - Total invoice amounts
payment_summary - Payment statistics and trends
revenue_trends - Revenue analysis over time
customer_growth - Customer acquisition and growth metrics
invoice_status_distribution - Invoice status breakdown
payment_performance - Payment timing and performance
top_customers - Highest value customers
monthly_revenue - Monthly revenue analysis
quarterly_summary - Quarterly business summary

Example result:

{
  "success": true,
  "metric": "customer_count",
  "data": {
    "total": 25,
    "active": 23,
    "archived": 2,
    "growth_rate": 15.4,
    "trends": [
      {
        "period": "2024-01",
        "count": 20,
        "growth": 0
      },
      {
        "period": "2024-02",
        "count": 22,
        "growth": 10.0
      },
      {
        "period": "2024-03",
        "count": 25,
        "growth": 13.6
      }
    ]
  },
  "summary": {
    "metric": "customer_count",
    "timestamp": "2024-03-15T10:30:00Z",
    "timeRange": "2024-01-01 to 2024-12-31",
    "resultCount": 1
  },
  "execution_time_ms": 89
}

Revenue Trends Example:

{
  "method": "tools/call",
  "params": {
    "name": "get_crm_analytics",
    "arguments": {
      "metric": "revenue_trends",
      "timeRange": {
        "period": "quarter"
      },
      "groupBy": "month"
    }
  }
}

Revenue Trends Result:

{
  "success": true,
  "metric": "revenue_trends",
  "data": {
    "total_revenue": 125000.00,
    "average_monthly": 41666.67,
    "growth_rate": 12.5,
    "trends": [
      {
        "month": "2024-01",
        "revenue": 38000.00,
        "invoices": 8,
        "growth": 0
      },
      {
        "month": "2024-02",
        "revenue": 42000.00,
        "invoices": 9,
        "growth": 10.5
      },
      {
        "month": "2024-03",
        "revenue": 45000.00,
        "invoices": 10,
        "growth": 7.1
      }
    ]
  },
  "summary": {
    "metric": "revenue_trends",
    "timestamp": "2024-03-15T10:30:00Z",
    "timeRange": "Q1 2024",
    "resultCount": 1
  },
  "execution_time_ms": 112
}

Business Operations Tools

execute_crm_action

What it does:
Executes business operations and automated workflows including sending emails, updating records, generating reports, and performing data imports/exports.

How to use it:

{
  "method": "tools/call",
  "params": {
    "name": "execute_crm_action",
    "arguments": {
      "action": "send",
      "entity": "customers",
      "targetId": 1,
      "data": {
        "type": "welcome_email",
        "subject": "Welcome to Our Services",
        "template": "welcome_template",
        "variables": {
          "customer_name": "Acme Corporation",
          "account_manager": "John Smith"
        }
      }
    }
  }
}

Available actions:

send - Send emails, notifications, or communications
review - Review and approve records or workflows
import - Import data from external sources
update - Update existing records
delete - Delete records (with confirmation)

Example result:

{
  "success": true,
  "action": "send",
  "entity": "customers",
  "result": {
    "message_id": "msg_123456789",
    "recipient": "contact@acme.com",
    "status": "sent",
    "sent_at": "2024-03-15T10:30:00Z",
    "template_used": "welcome_template"
  },
  "execution_time_ms": 234
}

Update Record Example:

{
  "method": "tools/call",
  "params": {
    "name": "execute_crm_action",
    "arguments": {
      "action": "update",
      "entity": "customers",
      "targetId": 1,
      "data": {
        "phone": "+1-555-9999",
        "address": "456 New Business Ave, City, State 12345"
      }
    }
  }
}

Update Result:

{
  "success": true,
  "action": "update",
  "entity": "customers",
  "result": {
    "updated_fields": ["phone", "address"],
    "previous_values": {
      "phone": "+1-555-0123",
      "address": "123 Business St, City, State 12345"
    },
    "new_values": {
      "phone": "+1-555-9999",
      "address": "456 New Business Ave, City, State 12345"
    },
    "updated_at": "2024-03-15T10:30:00Z"
  },
  "execution_time_ms": 156
}

Advanced Usage Examples

Customer Analysis Query

{
  "method": "tools/call",
  "params": {
    "name": "query_crm_data",
    "arguments": {
      "entity": "customers",
      "filters": {
        "isArchived": false,
        "purchaseOrders": {
          "some": {
            "status": "ACTIVE"
          }
        }
      },
      "include": {
        "purchaseOrders": {
          "include": {
            "invoices": true
          }
        }
      }
    }
  }
}

Payment Performance Analysis

{
  "method": "tools/call",
  "params": {
    "name": "get_crm_analytics",
    "arguments": {
      "metric": "payment_performance",
      "timeRange": {
        "period": "month"
      }
    }
  }
}

Automated Customer Follow-up

{
  "method": "tools/call",
  "params": {
    "name": "execute_crm_action",
    "arguments": {
      "action": "send",
      "entity": "customers",
      "targetId": 1,
      "data": {
        "type": "follow_up",
        "subject": "Follow-up on Recent Project",
        "template": "project_followup",
        "variables": {
          "customer_name": "Acme Corporation",
          "project_name": "Digital Transformation",
          "next_steps": "Schedule review meeting"
        }
      }
    }
  }
}

Error Handling

All tools return standardized error responses:

{
  "success": false,
  "error": "Insufficient permissions to access customer data",
  "error_code": "PERMISSION_DENIED",
  "execution_time_ms": 12
}

Common error codes:

PERMISSION_DENIED - Insufficient permissions for the requested operation
INVALID_PARAMETERS - Invalid or missing required parameters
ENTITY_NOT_FOUND - Requested entity or record not found
VALIDATION_ERROR - Data validation failed
RATE_LIMIT_EXCEEDED - API rate limit exceeded
INTERNAL_ERROR - Internal server error

Performance Considerations

Query Optimization: Use specific filters to reduce data transfer
Pagination: Use limit and offset for large datasets
Caching: Results are cached for improved performance
Rate Limiting: Respect API rate limits (100 requests/minute per API key)

Security Notes

All API calls require valid authentication
Data access is restricted by API key permissions
All operations are logged for audit purposes
Sensitive data is encrypted in transit and at rest

MCP Tool Reference

Tool Categories

1. Core MCP Tools

2. Consultia Data Access Tools

3. Business Intelligence Tools

4. Business Operations Tools

Core MCP Tools

list_tools

call_tool

Consultia Data Access Tools

query_crm_data

Business Intelligence Tools

get_crm_analytics

Business Operations Tools

execute_crm_action

Advanced Usage Examples

Customer Analysis Query

Payment Performance Analysis

Automated Customer Follow-up

Error Handling

Performance Considerations

Security Notes

Page Information

Title

Description

Last Updated

Navigation

Quick Links