Limiting Available Tools with MCP_TOOLS Environment Variable - skindyk/testrail-mcp-server GitHub Wiki

Overview

The MCP_TOOLS environment variable allows you to restrict which TestRail tools are available to your MCP client. This is useful for:

  • 🔒 Security: Limit access to sensitive operations
  • 🎯 Simplification: Reduce tool complexity for specific use cases
  • 👥 Role-based access: Create different toolsets for different team members

How It Works

  • Default behavior: All 119 tools are available if MCP_TOOLS is not set
  • Restriction mode: Only specified tools are available when MCP_TOOLS is configured
  • Format support: JSON array or comma-separated string
  • Case sensitive: Tool names must match exactly

Configuration Formats

JSON Array Format (IntelliJ IDEA, VS Code)

{
  "servers": {
    "testrail": {
      "command": "node",
      "args": ["C:\\path\\to\\your\\testrail-mcp\\wrapper.cjs"],
      "env": {
        "TESTRAIL_URL": "https://your-testrail-instance.testrail.io",
        "TESTRAIL_USERNAME": "[email protected]",
        "TESTRAIL_PASSWORD": "your-api-key-or-password",
        "MCP_TOOLS": ["get_projects", "get_cases", "add_case", "update_case"]
      }
    }
  }
}

Comma-Separated String Format (Roo Code)

{
  "servers": {
    "testrail": {
      "command": "node",
      "args": ["C:\\path\\to\\your\\testrail-mcp\\wrapper.cjs"],
      "env": {
        "TESTRAIL_URL": "https://your-testrail-instance.testrail.io",
        "TESTRAIL_USERNAME": "[email protected]",
        "TESTRAIL_PASSWORD": "your-api-key-or-password",
        "MCP_TOOLS": "get_projects,get_cases,add_case,update_case"
      }
    }
  }
}

Common Use Cases

1. Read-Only Access

Perfect for stakeholders who need to view data but shouldn't modify anything:

"MCP_TOOLS": [
  "get_projects", "get_project",
  "get_suites", "get_suite", 
  "get_cases", "get_case",
  "get_runs", "get_run",
  "get_results", "get_results_for_case", "get_results_for_run",
  "get_plans", "get_plan",
  "get_sections", "get_section",
  "get_milestones", "get_milestone",
  "get_users", "get_user"
]

2. Test Execution Only

For testers who only need to execute tests and add results:

"MCP_TOOLS": [
  "get_projects", "get_cases", "get_runs", "get_tests",
  "add_result", "add_result_for_case", "add_results", "add_results_for_cases",
  "get_results", "get_results_for_case", "get_results_for_run"
]

3. Test Case Management

For test case authors and maintainers:

"MCP_TOOLS": [
  "get_projects", "get_suites", "get_sections", "get_cases",
  "add_case", "update_case", "delete_case", "copy_cases_to_section",
  "add_section", "update_section", "move_section",
  "get_case_fields", "get_case_types", "get_priorities"
]

4. Project Management

For project managers and leads:

"MCP_TOOLS": [
  "get_projects", "get_project", "add_project", "update_project",
  "get_plans", "get_plan", "add_plan", "update_plan", "close_plan",
  "get_runs", "get_run", "add_run", "update_run", "close_run",
  "get_milestones", "get_milestone", "add_milestone", "update_milestone",
  "get_reports", "run_report"
]

5. Reporting Only

For analysts who only need to generate reports:

"MCP_TOOLS": [
  "get_projects", "get_runs", "get_results_for_run",
  "get_plans", "get_reports", "run_report",
  "get_cross_project_reports", "run_cross_project_report"
]

6. Basic Operations

Minimal toolset for simple workflows:

"MCP_TOOLS": [
  "get_projects", "get_cases", "get_runs", 
  "add_result", "get_results"
]

Tool Categories Reference

Core Data Access (Read-Only)

get_projects, get_project, get_suites, get_suite, get_cases, get_case,
get_runs, get_run, get_results, get_results_for_case, get_results_for_run,
get_plans, get_plan, get_sections, get_section, get_milestones, get_milestone,
get_users, get_user, get_user_by_email, get_tests, get_test

Test Case Management

add_case, update_case, delete_case, copy_cases_to_section,
update_cases, move_cases_to_section, delete_cases,
get_history_for_case

Test Execution

add_run, update_run, close_run, delete_run,
add_result, add_result_for_case, add_results, add_results_for_cases

Test Planning

add_plan, update_plan, close_plan, delete_plan,
add_plan_entry, update_plan_entry, delete_plan_entry,
add_run_to_plan_entry, update_run_in_plan_entry, delete_run_from_plan_entry

Organization & Structure

add_suite, update_suite, delete_suite,
add_section, update_section, move_section, delete_section,
add_milestone, update_milestone, delete_milestone

Configuration & Metadata

get_case_fields, add_case_field, get_case_types, get_priorities,
get_statuses, get_templates, get_result_fields, get_roles,
get_configs, add_config_group, add_config, update_config_group,
update_config, delete_config_group, delete_config

Advanced Features

get_reports, run_report, get_cross_project_reports, run_cross_project_report,
get_bdd, add_bdd, get_shared_steps, get_shared_step, add_shared_step,
update_shared_step, delete_shared_step, get_labels, update_label

Attachments

get_attachments_for_case, get_attachments_for_plan, get_attachments_for_plan_entry,
get_attachments_for_result, get_attachments_for_run, get_attachments_for_test,
add_attachment_to_case, add_attachment_to_plan, add_attachment_to_plan_entry,
add_attachment_to_result, add_attachment_to_run, get_attachment, delete_attachment

Enterprise Features

get_datasets, add_dataset, update_dataset, delete_dataset,
get_variables, add_variable, update_variable, delete_variable,
get_groups, get_group, add_group, update_group, delete_group

Security Considerations

Dangerous Operations

Consider excluding these tools for non-admin users:

  • delete_project - Permanently removes projects
  • delete_suite - Removes entire test suites
  • delete_cases - Bulk deletion of test cases
  • delete_run - Removes test runs and results
  • delete_plan - Removes test plans

Sensitive Data Access

Limit access to user and configuration data:

  • get_users - User information
  • add_case_field - System configuration
  • get_roles - Permission information
  • get_groups - User group data

Best Practices

1. Start Restrictive

Begin with minimal tools and add as needed:

"MCP_TOOLS": ["get_projects", "get_cases", "get_runs"]

2. Group by Role

Create different configurations for different team roles:

  • Testers: Execution-focused tools
  • Developers: Case creation and updates
  • Managers: Planning and reporting tools
  • Stakeholders: Read-only access

3. Document Your Choices

Comment your configuration to explain tool selections:

{
  "// Comment": "Tools for test execution team - read access + result reporting",
  "MCP_TOOLS": ["get_projects", "get_cases", "add_result", "get_results"]
}

4. Test Configurations

Verify your tool restrictions work as expected:

  1. Configure with limited tools
  2. Test that restricted tools are not available
  3. Confirm required tools work properly

5. Regular Review

Periodically review and update tool restrictions:

  • Remove unused tools
  • Add tools for new workflows
  • Adjust based on team feedback

Complete Tool Reference

Here's the complete list of all 119 available tools:

get_projects, get_project, add_project, update_project, delete_project,
get_suites, get_suite, add_suite, update_suite, delete_suite,
get_cases, get_case, add_case, update_case, delete_case, get_history_for_case, copy_cases_to_section, update_cases, move_cases_to_section, delete_cases,
get_runs, get_run, add_run, update_run, close_run, delete_run,
get_results, get_results_for_case, get_results_for_run, add_result, add_result_for_case, add_results, add_results_for_cases,
get_plans, get_plan, add_plan, update_plan, close_plan, delete_plan, add_plan_entry, update_plan_entry, delete_plan_entry, add_run_to_plan_entry, update_run_in_plan_entry, delete_run_from_plan_entry,
get_sections, get_section, add_section, update_section, move_section, delete_section,
get_milestones, get_milestone, add_milestone, update_milestone, delete_milestone,
get_users, get_user, get_user_by_email,
get_case_fields, add_case_field, get_case_types, get_priorities, get_statuses, get_templates, get_result_fields, get_roles,
get_reports, run_report, get_cross_project_reports, run_cross_project_report,
get_attachments_for_case, get_attachments_for_plan, get_attachments_for_plan_entry, get_attachments_for_result, get_attachments_for_run, get_attachments_for_test, add_attachment_to_case, add_attachment_to_plan, add_attachment_to_plan_entry, add_attachment_to_result, add_attachment_to_run, get_attachment, delete_attachment,
get_bdd, add_bdd,
get_configs, add_config_group, add_config, update_config_group, update_config, delete_config_group, delete_config,
get_tests, get_test, update_test, update_tests,
get_labels, get_label, update_label,
get_shared_steps, get_shared_step, get_shared_step_history, add_shared_step, update_shared_step, delete_shared_step,
get_datasets, get_dataset, add_dataset, update_dataset, delete_dataset,
get_variables, add_variable, update_variable, delete_variable,
get_groups, get_group, add_group, update_group, delete_group

Examples for Different MCP Clients

IntelliJ IDEA / VS Code

{
  "servers": {
    "testrail": {
      "command": "node",
      "args": ["C:\\path\\to\\testrail-mcp\\wrapper.cjs"],
      "env": {
        "TESTRAIL_URL": "https://company.testrail.io",
        "TESTRAIL_USERNAME": "[email protected]",
        "TESTRAIL_PASSWORD": "api-key",
        "MCP_TOOLS": ["get_projects", "get_cases", "add_result"]
      }
    }
  }
}

Claude Desktop / Roo Code

{
  "mcpServers": {
    "testrail": {
      "command": "node",
      "args": ["C:\\path\\to\\testrail-mcp\\wrapper.cjs"],
      "env": {
        "TESTRAIL_URL": "https://company.testrail.io",
        "TESTRAIL_USERNAME": "[email protected]",
        "TESTRAIL_PASSWORD": "api-key",
        "MCP_TOOLS": "get_projects,get_cases,add_result"
      }
    }
  }
}