ServiceNow MCP Server

Instructions

Implementation Reference

• src/servicenow_mcp/tools/catalog_variables.py:81-152 (handler)

  The handler function that implements the core logic for creating a catalog item variable by constructing a payload and POSTing to ServiceNow's item_option_new table API endpoint.

  def create_catalog_item_variable(
      config: ServerConfig,
      auth_manager: AuthManager,
      params: CreateCatalogItemVariableParams,
  ) -> CatalogItemVariableResponse:
      """
      Create a new variable (form field) for a catalog item.
  
      Args:
          config: Server configuration.
          auth_manager: Authentication manager.
          params: Parameters for creating a catalog item variable.
  
      Returns:
          Response with information about the created variable.
      """
      api_url = f"{config.instance_url}/api/now/table/item_option_new"
  
      # Build request data
      data = {
          "cat_item": params.catalog_item_id,
          "name": params.name,
          "type": params.type,
          "question_text": params.label,
          "mandatory": str(params.mandatory).lower(),  # ServiceNow expects "true"/"false" strings
      }
  
      if params.help_text:
          data["help_text"] = params.help_text
      if params.default_value:
          data["default_value"] = params.default_value
      if params.description:
          data["description"] = params.description
      if params.order is not None:
          data["order"] = params.order
      if params.reference_table:
          data["reference"] = params.reference_table
      if params.reference_qualifier:
          data["reference_qual"] = params.reference_qualifier
      if params.max_length:
          data["max_length"] = params.max_length
      if params.min is not None:
          data["min"] = params.min
      if params.max is not None:
          data["max"] = params.max
  
      # Make request
      try:
          response = requests.post(
              api_url,
              json=data,
              headers=auth_manager.get_headers(),
              timeout=config.timeout,
          )
          response.raise_for_status()
  
          result = response.json().get("result", {})
  
          return CatalogItemVariableResponse(
              success=True,
              message="Catalog item variable created successfully",
              variable_id=result.get("sys_id"),
              details=result,
          )
  
      except requests.RequestException as e:
          logger.error(f"Failed to create catalog item variable: {e}")
          return CatalogItemVariableResponse(
              success=False,
              message=f"Failed to create catalog item variable: {str(e)}",
          )

• src/servicenow_mcp/tools/catalog_variables.py:19-36 (schema)

  Pydantic model defining the input parameters for the create_catalog_item_variable tool.

  class CreateCatalogItemVariableParams(BaseModel):
      """Parameters for creating a catalog item variable."""
  
      catalog_item_id: str = Field(..., description="The sys_id of the catalog item")
      name: str = Field(..., description="The name of the variable (internal name)")
      type: str = Field(..., description="The type of variable (e.g., string, integer, boolean, reference)")
      label: str = Field(..., description="The display label for the variable")
      mandatory: bool = Field(False, description="Whether the variable is required")
      help_text: Optional[str] = Field(None, description="Help text to display with the variable")
      default_value: Optional[str] = Field(None, description="Default value for the variable")
      description: Optional[str] = Field(None, description="Description of the variable")
      order: Optional[int] = Field(None, description="Display order of the variable")
      reference_table: Optional[str] = Field(None, description="For reference fields, the table to reference")
      reference_qualifier: Optional[str] = Field(None, description="For reference fields, the query to filter reference options")
      max_length: Optional[int] = Field(None, description="Maximum length for string fields")
      min: Optional[int] = Field(None, description="Minimum value for numeric fields")
      max: Optional[int] = Field(None, description="Maximum value for numeric fields")

• src/servicenow_mcp/utils/tool_utils.py:457-463 (registration)

  Tool registration in the central tool_definitions dictionary returned by get_tool_definitions, mapping the tool name to its handler, schema, return type, description, and serialization method.

  "create_catalog_item_variable": (
      create_catalog_item_variable_tool,
      CreateCatalogItemVariableParams,
      Dict[str, Any],  # Expects dict
      "Create a new catalog item variable",
      "dict",  # Tool returns Pydantic model
  ),

• src/servicenow_mcp/utils/tool_utils.py:47-47 (registration)

  Import and aliasing of the handler function for use in tool registration.

  create_catalog_item_variable as create_catalog_item_variable_tool,

• src/servicenow_mcp/tools/__init__.py:18-19 (registration)

  Import of the create_catalog_item_variable function into the tools package namespace.

  from servicenow_mcp.tools.catalog_variables import (
      create_catalog_item_variable,