Skip to main content
Glama
deenesjakoruzh
severity1

terraform-cloud-mcp

by severity1
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

force_cancel_run

Forcefully cancel a Terraform Cloud run that is stuck and not responding to normal cancellation, bypassing graceful shutdown to unlock the workspace immediately.

Instructions

Forcefully cancel a run immediately

Immediately terminates a run that hasn't responded to a normal cancel request. Use this as a last resort when a run is stuck and not responding to regular cancellation. This action bypasses the graceful shutdown process and forces the workspace to be unlocked.

API endpoint: POST /runs/{run_id}/actions/force-cancel

Args: run_id: The ID of the run to force cancel (format: "run-xxxxxxxx") comment: An optional explanation for why the run was force canceled

Returns: Run status update confirming forced cancellation with timestamp, user information, and workspace unlock status

See: docs/tools/run.md for reference documentation

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
run_idYes
commentNo

Implementation Reference

  • terraform_cloud_mcp/tools/runs.py:367-399 (handler)
    The main execution handler for the 'force_cancel_run' tool. It creates a RunActionRequest, optionally adds a comment to the payload, and performs a POST request to the Terraform Cloud API endpoint '/runs/{run_id}/actions/force-cancel' to forcefully cancel the specified run.
    @handle_api_errors
async def force_cancel_run(run_id: str, comment: str = "") -> APIResponse:
    """Forcefully cancel a run immediately

    Immediately terminates a run that hasn't responded to a normal cancel request.
    Use this as a last resort when a run is stuck and not responding to regular
    cancellation. This action bypasses the graceful shutdown process and forces
    the workspace to be unlocked.

    API endpoint: POST /runs/{run_id}/actions/force-cancel

    Args:
        run_id: The ID of the run to force cancel (format: "run-xxxxxxxx")
        comment: An optional explanation for why the run was force canceled

    Returns:
        Run status update confirming forced cancellation with timestamp,
        user information, and workspace unlock status

    See:
        docs/tools/run.md for reference documentation
    """
    request = RunActionRequest(run_id=run_id, comment=comment)

    # Create payload if comment is provided
    payload = {}
    if request.comment:
        payload = {"comment": request.comment}

    # Make API request
    return await api_request(
        f"runs/{run_id}/actions/force-cancel", method="POST", data=payload
    )
  • terraform_cloud_mcp/server.py:71-71 (registration)
    The registration of the 'force_cancel_run' tool in the MCP server using FastMCP's mcp.tool decorator with write permissions configuration.
    mcp.tool(**write_tool_config)(runs.force_cancel_run)

Tool Definition Quality

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds significant behavioral context beyond the readOnlyHint=false annotation. It explains that this action 'bypasses the graceful shutdown process and forces the workspace to be unlocked,' which are critical behavioral traits not captured in annotations. However, it doesn't mention potential side effects like data loss or system instability.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with purpose upfront, usage guidance, API endpoint reference, parameter details, return description, and documentation link. Every sentence adds value, though the API endpoint line could be considered redundant for an AI agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive tool with no output schema, the description provides good coverage: purpose, usage context, behavioral impact, parameter semantics, and return format. It lacks explicit error conditions or permissions required, but the 'last resort' warning and workspace unlock details offer sufficient context for safe use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates well by explaining both parameters: run_id format ('run-xxxxxxxx') and comment purpose ('optional explanation for why the run was force canceled'). It adds meaningful context beyond the bare schema, though it could specify comment length or content constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('forcefully cancel a run immediately') and distinguishes it from the sibling 'cancel_run' tool by explaining it's for when normal cancellation fails. It specifies the resource (run) and the forceful nature of the operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use this tool ('as a last resort when a run is stuck and not responding to regular cancellation') and provides clear exclusion criteria (bypasses graceful shutdown). It references the alternative 'cancel_run' implicitly by contrasting with 'normal cancel request'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/severity1/terraform-cloud-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server