Workspace MCP API

Tools for managing workspaces (a.k.a. teams) including discovery and CRUD operations.

Errors and retries

All MCP tools return a uniform ToolResponse envelope (ok, result, issues[]). When ok: false, inspect issues and apply retries/backoff (respect retry_after_ms for 429 and back off on 5xx/transient errors). See Errors and Retries (MCP) for details.

Tools

workspace.list

Lists all workspaces (teams) the current token can access. This is a read-only discovery call that helps you obtain team_id values for downstream operations like space.list. The tool returns a ToolResponse envelope with items[] where each item includes { team_id, name }.

• Parameters: none

{}

• Returns: WorkspaceListResult in ToolResponse

{
  "ok": true, // Tool succeeded
  "result": {
    "items": [
      {
        "team_id": "team_1", // Workspace (team) ID
        "name": "Engineering" // Workspace name
      }
    ]
  },
  "issues": [] // Optional warnings/issues collected during execution
}

• Errors
  • AUTH_ERROR (401), FORBIDDEN (403)
  • RATE_LIMIT (429)
  • UPSTREAM_ERROR (5xx/timeout)

workspace.create

Creates a new workspace (team) with a name, optional color, and avatar.

• Parameters: WorkspaceCreateInput

{
  "name": "Engineering Team", // Required: Workspace name
  "color": "#3498db", // Optional: Hex color for workspace UI
  "avatar": "https://example.com/avatar.png" // Optional: Avatar URL
}

• Returns: WorkspaceResult in ToolResponse

{
  "ok": true,
  "result": {
    "id": "9018752317", // Workspace ID
    "name": "Engineering Team",
    "color": "#3498db",
    "avatar": "https://example.com/avatar.png"
  },
  "issues": []
}

• Errors
  • VALIDATION_ERROR (invalid input)
  • AUTH_ERROR (401), FORBIDDEN (403)
  • RATE_LIMIT (429)
  • UPSTREAM_ERROR (5xx/timeout)

workspace.get

Retrieves details for a specific workspace by ID.

• Parameters: WorkspaceGetInput

{
  "workspace_id": "9018752317" // Required: Workspace ID to retrieve
}

• Returns: WorkspaceResult in ToolResponse

{
  "ok": true,
  "result": {
    "id": "9018752317",
    "name": "Engineering Team",
    "color": "#3498db",
    "avatar": "https://example.com/avatar.png"
  },
  "issues": []
}

• Errors
  • NOT_FOUND (workspace doesn't exist)
  • VALIDATION_ERROR (invalid input)
  • AUTH_ERROR (401), FORBIDDEN (403)
  • RATE_LIMIT (429)
  • UPSTREAM_ERROR (5xx/timeout)

workspace.update

Updates an existing workspace's name, color, or avatar.

• Parameters: WorkspaceUpdateInput

{
  "workspace_id": "9018752317", // Required: Workspace ID to update
  "name": "Updated Team Name", // Optional: New workspace name
  "color": "#e74c3c", // Optional: New hex color
  "avatar": "https://example.com/new-avatar.png" // Optional: New avatar URL
}

• Returns: WorkspaceResult in ToolResponse

{
  "ok": true,
  "result": {
    "id": "9018752317",
    "name": "Updated Team Name",
    "color": "#e74c3c",
    "avatar": "https://example.com/new-avatar.png"
  },
  "issues": []
}

• Errors
  • NOT_FOUND (workspace doesn't exist)
  • VALIDATION_ERROR (invalid input)
  • AUTH_ERROR (401), FORBIDDEN (403)
  • RATE_LIMIT (429)
  • UPSTREAM_ERROR (5xx/timeout)

workspace.delete

Deletes a workspace by ID. This action cannot be undone.

• Parameters: WorkspaceDeleteInput

{
  "workspace_id": "9018752317" // Required: Workspace ID to delete
}

• Returns: DeletionResult in ToolResponse

{
  "ok": true,
  "result": {
    "ok": true // True if deletion succeeded
  },
  "issues": []
}

• Errors
  • NOT_FOUND (workspace doesn't exist)
  • VALIDATION_ERROR (invalid input)
  • AUTH_ERROR (401), FORBIDDEN (403)
  • RATE_LIMIT (429)
  • UPSTREAM_ERROR (5xx/timeout)