Optuna MCP Server

Instructions

    This feature can only be used for single-objective optimization. If your study is multi-objective, use best_trials instead.
    

Implementation Reference

• optuna_mcp/server.py:328-350 (handler)

  The handler function for the 'best_trial' tool. Retrieves and returns the best trial from the Optuna study as a structured TrialResponse.

  @mcp.tool(structured_output=True)
  def best_trial() -> TrialResponse:
      """Get the best trial
  
      This feature can only be used for single-objective optimization. If your study is multi-objective, use best_trials instead.
      """
      if mcp.study is None:
          raise McpError(
              ErrorData(
                  code=INTERNAL_ERROR,
                  message="No study has been created. Please create a study first.",
              )
          )
  
      trial = mcp.study.best_trial
      return TrialResponse(
          trial_number=trial.number,
          params=trial.params,
          values=trial.values,
          user_attrs=trial.user_attrs,
          system_attrs=trial.system_attrs,
      )

• optuna_mcp/server.py:84-98 (schema)

  Pydantic BaseModel defining the structured output schema for the best_trial tool (and other trial responses).

  class TrialResponse(BaseModel):
      trial_number: int
      params: dict[str, typing.Any] | None = Field(
          default=None, description="The parameter values suggested by the trial."
      )
      values: list[float] | None = Field(
          default=None, description="The objective values of the trial."
      )
      user_attrs: dict[str, typing.Any] | None = Field(
          default=None, description="User-defined attributes for the trial."
      )
      system_attrs: dict[str, typing.Any] | None = Field(
          default=None, description="System-defined attributes for the trial."
      )

• optuna_mcp/server.py:686-686 (registration)

  The call to register_tools which defines and registers the best_trial tool among others in the OptunaMCP instance.

  mcp = register_tools(mcp)