Pull Request Checklist

Before submitting, make sure you've checked the following:

• Target branch: Verify that the pull request targets the dev branch.
• Description: Provide a concise description of the changes made in this pull request down below.
• Changelog: Ensure a changelog entry following the format of Keep a Changelog is added at the bottom of the PR description.
• Documentation: No documentation update required - uses existing TOOL_SERVER_CONNECTIONS env var.
• Dependencies: No new dependencies added.
• Testing: Comprehensive manual and automated testing performed (see Testing section below).
• Agentic AI Code: This PR has gone through manual review and extensive manual testing in Kubernetes environment.
• Code review: Self-review completed, follows existing code patterns in lifespan().
• Title Prefix: fix

Changelog Entry

Description

Fix the issue where TOOL_SERVER_CONNECTIONS environment variable is set but tool servers are not actually initialized until the user manually visits the Admin Panel and clicks Save.

Problem: TOOL_SERVER_CONNECTIONS is a PersistentConfig that only pre-populates the Admin Panel settings. The tools don't become available until set_tool_servers() is called, which currently only happens when a user manually saves the config.

Solution: Call set_tool_servers() during application startup (in the lifespan() function) when TOOL_SERVER_CONNECTIONS has entries. This makes tools available immediately without requiring manual intervention.

Added

• Startup initialization in lifespan() function to call set_tool_servers() when TOOL_SERVER_CONNECTIONS is configured
• Import of set_tool_servers from open_webui.utils.tools

Changed

• N/A

Deprecated

• N/A

Removed

• N/A

Fixed

• Tool servers configured via TOOL_SERVER_CONNECTIONS environment variable now initialize automatically on startup without requiring manual Admin Panel save (Fixes issue: tools does not appear on chat Window when configure with TOOL_SERVER_CONNECTIONS env #18140)

Security

• N/A

Breaking Changes

• N/A

Additional Information

Use Case: Users deploying Open-WebUI in Kubernetes/containerized environments want to pre-configure tool servers via environment variables for GitOps/IaC workflows. Currently this requires:

1. Set TOOL_SERVER_CONNECTIONS env var
2. Wait for pod to start
3. Manually log into Admin Panel
4. Navigate to External Tools
5. Click Save (without changing anything)
6. Tools finally become available

With this fix, steps 3-6 are eliminated - tools work immediately on startup.

Code Pattern: The implementation follows the exact same pattern used for ENABLE_BASE_MODELS_CACHE initialization at lines 628-647 in main.py, using a mock Request object.

Comprehensive Testing Documentation

Unit Tests (10/10 Passed)

Created standalone unit test suite (test_tool_server_startup_standalone.py) covering:

Integration Testing in Kubernetes

Environment:

• Kubernetes cluster (MicroK8s)
• Open-WebUI deployed via Helm chart
• MCPO (MCP-to-OpenAPI proxy) tool servers

Test Configuration:

env:
  - name: TOOL_SERVER_CONNECTIONS
    value: '[{"url":"http://mcpo-filesystem:8080/openapi.json","info":{"id":"filesystem","name":"Filesystem"},"type":"openapi","auth_type":"none"},{"url":"http://mcpo-fetch:8080/openapi.json","info":{"id":"fetch","name":"Fetch"},"type":"openapi","auth_type":"none"},{"url":"http://mcpo-memory:8080/openapi.json","info":{"id":"memory","name":"Memory"},"type":"openapi","auth_type":"none"},{"url":"http://mcpo-sequential-thinking:8080/openapi.json","info":{"id":"sequential-thinking","name":"Sequential Thinking"},"type":"openapi","auth_type":"none"},{"url":"http://mcpo-time:8080/openapi.json","info":{"id":"time","name":"Time"},"type":"openapi","auth_type":"none"}]'

Test Results:

1. Startup Initialization Test

   • Method: Deployed pod and observed startup logs
   • Expected: Log message "Initializing N tool server(s) from TOOL_SERVER_CONNECTIONS..."
   • Actual:

     INFO | open_webui.main:lifespan:653 - Initializing 5 tool server(s) from TOOL_SERVER_CONNECTIONS...
     INFO | open_webui.main:lifespan:674 - Tool servers initialized successfully
     

   • Result: PASS

2. Health Check Test

   • Method: curl http://localhost:8080/health
   • Expected: {"status":true}
   • Actual: {"status":true}
   • Result: PASS

3. Pod Stability Test

   • Method: Observed pod status over 10+ minutes
   • Expected: Pod remains Running, no restarts
   • Actual: open-webui-xxx 1/1 Running 0 12m
   • Result: PASS

4. Regression Test - Manual Save

   • Method: After startup, navigated to Admin Panel > External Tools and clicked Save
   • Expected: Manual save flow still works, tools remain available
   • Actual: Save completed without error, tools working
   • Result: PASS

5. Empty Configuration Test

   • Method: Deployed without TOOL_SERVER_CONNECTIONS env var
   • Expected: No initialization log, app starts normally
   • Actual: No "Initializing" log, app started normally
   • Result: PASS

6. Error Handling Test

   • Method: Configured unreachable tool server URL
   • Expected: Error logged, app continues to start
   • Actual: ERROR | Failed to initialize tool servers: ..., app continued
   • Result: PASS

Code Review Checklist

• Import added at correct location (line 63, with other utils imports)
• Follows existing code pattern (same as ENABLE_BASE_MODELS_CACHE init at lines 628-647)
• Uses proper async/await
• Includes error handling with try/except
• Logs initialization start and success/failure
• References issue number in comment
• No security vulnerabilities introduced (uses internal mock request only)

Screenshots or Videos

Startup logs showing auto-initialization:

INFO     | open_webui.main:lifespan:605 - Installing external dependencies of functions and tools...
INFO     | open_webui.main:lifespan:653 - Initializing 5 tool server(s) from TOOL_SERVER_CONNECTIONS...
INFO     | open_webui.main:lifespan:674 - Tool servers initialized successfully

Health endpoint confirms service running:

$ curl http://localhost:8080/health
{"status":true}

Pod status (stable, no restarts):

NAME                        READY   STATUS    RESTARTS   AGE
open-webui-xxx              1/1     Running   0          12m

Unit test results:

======================================================================
Tool Server Startup Initialization Tests
======================================================================

Running tests...

  PASS: initialization_called_when_connections_exist
  PASS: initialization_skipped_when_no_connections
  PASS: error_handling_on_initialization_failure
  PASS: multiple_tool_servers_count
  PASS: tool_servers_populated_in_app_state
  PASS: openapi_server_config_format
  PASS: mcp_server_config_format
  PASS: authenticated_server_config_format
  PASS: logging_message_format
  PASS: empty_list_vs_none_handling

----------------------------------------------------------------------
Results: 10 passed, 0 failed
----------------------------------------------------------------------

All tests passed!

Testing Confirmation

• I have personally tested ALL changes in this PR
• How I tested:
  • Created and ran 10 unit tests (all passed)
  • Deployed to Kubernetes with 5 MCPO tool servers
  • Verified startup initialization logs
  • Verified health endpoint
  • Verified pod stability (no restarts)
  • Verified no regression in manual Admin Panel save flow
  • Tested error handling with unreachable server
  • Tested empty configuration (no env var set)
• Verified no regressions - existing manual save flow in Admin Panel still works as expected

Contributor License Agreement

By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.