list_workspaces
Retrieve and filter workspaces in a Terraform Cloud organization to discover configurations or find specific workspaces by name.
Instructions
List workspaces in an organization.
Retrieves a paginated list of all workspaces in a Terraform Cloud organization. Results can be filtered using a search string to find specific workspaces by name. Use this tool to discover existing workspaces, check workspace configurations, or find specific workspaces by partial name match.
API endpoint: GET /organizations/{organization}/workspaces
Args: organization: The name of the organization to list workspaces from page_number: The page number to return (default: 1) page_size: The number of items per page (default: 20, max: 100) search: Optional search string to filter workspaces by name
Returns: Paginated list of workspaces with their configuration settings and metadata
See: docs/tools/workspace.md for reference documentation
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| organization | Yes | ||
| page_number | No | ||
| page_size | No | ||
| search | No |
Implementation Reference
- The main handler function that executes the list_workspaces tool logic. It validates input using WorkspaceListRequest, constructs query parameters, and makes a GET request to the Terraform Cloud API endpoint /organizations/{organization}/workspaces.
@handle_api_errors async def list_workspaces( organization: str, page_number: int = 1, page_size: int = 20, search: Optional[str] = None, ) -> APIResponse: """List workspaces in an organization. Retrieves a paginated list of all workspaces in a Terraform Cloud organization. Results can be filtered using a search string to find specific workspaces by name. Use this tool to discover existing workspaces, check workspace configurations, or find specific workspaces by partial name match. API endpoint: GET /organizations/{organization}/workspaces Args: organization: The name of the organization to list workspaces from page_number: The page number to return (default: 1) page_size: The number of items per page (default: 20, max: 100) search: Optional search string to filter workspaces by name Returns: Paginated list of workspaces with their configuration settings and metadata See: docs/tools/workspace.md for reference documentation """ # Create request using Pydantic model for validation request = WorkspaceListRequest( organization=organization, page_number=page_number, page_size=page_size, search=search, ) params = query_params(request) return await api_request( f"organizations/{organization}/workspaces", method="GET", params=params ) - terraform_cloud_mcp/server.py:53-53 (registration)Registration of the list_workspaces tool using FastMCP's mcp.tool() decorator, making it available in the MCP server.
mcp.tool()(workspaces.list_workspaces) - Pydantic model defining the input schema for list_workspaces, used for validation of parameters like organization, page_number, page_size, and search.
class WorkspaceListRequest(APIRequest): """Request parameters for listing workspaces in an organization. Defines the parameters for the workspace listing API including pagination and search filtering options. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces#list-workspaces See: docs/models/workspace.md for reference """ organization: str = Field( ..., # No alias needed as field name matches API field name description="The name of the organization to list workspaces from", ) page_number: Optional[int] = Field(1, ge=1, description="Page number to fetch") page_size: Optional[int] = Field( 20, ge=1, le=100, description="Number of results per page" ) search: Optional[str] = Field(None, description="Substring to search for")