[PR #114] [CLOSED] fix: ensure MCP server tools are loaded before generating API docs or OpenWebUI integration #174

New issue

Closed

opened 2026-10-18 21:12:26 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-18 21:12:26 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/open-webui/mcpo/pull/114
Author: @Lin-jun-xiang
Created: 5/2/2025
Status: ❌ Closed

Base: main ← Head: fix/server-startup-delay

📝 Commits (1)

46586eb fix: wait for MCP server tools to be ready before listing (tools_timeout/tools_interval)

📊 Changes

3 files changed (+62 additions, -5 deletions)

View changed files

📝 src/mcpo/__init__.py (+8 -0)
📝 src/mcpo/main.py (+34 -5)
📝 src/mcpo/utils/main.py (+20 -0)

📄 Description

Pull Request Checklist

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

Target branch: Please verify that the pull request targets the dev branch.
Description: Provide a concise description of the changes made in this pull request.
Changelog: Ensure a changelog entry following the format of Keep a Changelog is added at the bottom of the PR description.
Dependencies: Are there any new dependencies? Have you updated the dependency versions in the documentation?
Testing: Have you written and run sufficient tests to validate the changes?
Code review: Have you performed a self-review of your code, addressing any coding standard issues and ensuring adherence to the project's coding standards?
Prefix: To clearly categorize this pull request, prefix the pull request title using one of the following:
- BREAKING CHANGE: Significant changes that may affect compatibility
- build: Changes that affect the build system or external dependencies
- ci: Changes to our continuous integration processes or workflows
- chore: Refactor, cleanup, or other non-functional code changes
- docs: Documentation update or addition
- feat: Introduces a new feature or enhancement to the codebase
- fix: Bug fix or error correction
- i18n: Internationalization or localization changes
- perf: Performance improvement
- refactor: Code restructuring for better maintainability, readability, or scalability
- style: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc.)
- test: Adding missing tests or correcting existing tests
- WIP: Work in progress, a temporary label for incomplete or ongoing work

Changelog Entry

Description

Adds configurable tools_timeout and tools_interval parameters to ensure the client waits for the MCP server to be fully ready before listing tools. This prevents issues where the tool list is empty if the server is not ready, which can break API docs and OpenWebUI integration.

I believe that every MCP server should provide tools—otherwise, there would be no point in building it. However, at the current stage, during the MCP connection process, some servers (when started via session.initialize) do not return any results from list_tools (instead, it returns an empty list []). It is necessary to wait for a while before calling list_tools to get the correct results.

Based on my testing with an MCP server developed using mcpsharp (please forgive me for not being able to share the code due to security concerns), starting the MCP server takes some time. When I added print(tools) to the source code, I observed the following output:

Starting MCP OpenAPI Proxy on 0.0.0.0:8000 with command: cmd.exe /c C:\example.exe
INFO:     Started server process 36m43812
INFO:     Waiting for application startup.
TEST PRINT: Tools:  []
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Since the tools have not yet been loaded, the API documentation (localhost:8000/docs) appears empty (at this point, OpenWebUI will hang), as shown below:

This improvement for MCPO serves as a temporary workaround. The ideal solution would be to address the issue on the MCP server side, ensuring that tools are available immediately after the server starts. However, this change provides a quick and efficient fix without impacting performance, and also adds a check to ensure MCP tools are present (otherwise, a runtime error is raised).

Added

tools_timeout and tools_interval parameters, configurable via CLI or config, passed through app state. ex: mcpo --port 8000 --tools-timeout 5 -- cmd.exe /c "C:\example.exe"
Polling mechanism in wait_list_tools to wait for tools to be available.

Changed

Deprecated

Removed

Fixed

Fixes issue where tools list could be empty if the server is not fully started.

Security

Breaking Changes

Additional Information

Screenshots or Videos

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/open-webui/mcpo/pull/114 **Author:** [@Lin-jun-xiang](https://github.com/Lin-jun-xiang) **Created:** 5/2/2025 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/server-startup-delay` --- ### 📝 Commits (1) - [`46586eb`](https://github.com/open-webui/mcpo/commit/46586eb5c8f82e9782920dea5f984a30ef4c3619) fix: wait for MCP server tools to be ready before listing (tools_timeout/tools_interval) ### 📊 Changes **3 files changed** (+62 additions, -5 deletions) <details> <summary>View changed files</summary> 📝 `src/mcpo/__init__.py` (+8 -0) 📝 `src/mcpo/main.py` (+34 -5) 📝 `src/mcpo/utils/main.py` (+20 -0) </details> ### 📄 Description # Pull Request Checklist **Before submitting, make sure you've checked the following:** - [x] **Target branch:** Please verify that the pull request targets the `dev` branch. - [x] **Description:** Provide a concise description of the changes made in this pull request. - [x] **Changelog:** Ensure a changelog entry following the format of [Keep a Changelog](https://keepachangelog.com/) is added at the bottom of the PR description. - [x] **Dependencies:** Are there any new dependencies? Have you updated the dependency versions in the documentation? - [x] **Testing:** Have you written and run sufficient tests to validate the changes? - [x] **Code review:** Have you performed a self-review of your code, addressing any coding standard issues and ensuring adherence to the project's coding standards? - [x] **Prefix:** To clearly categorize this pull request, prefix the pull request title using one of the following: - **BREAKING CHANGE**: Significant changes that may affect compatibility - **build**: Changes that affect the build system or external dependencies - **ci**: Changes to our continuous integration processes or workflows - **chore**: Refactor, cleanup, or other non-functional code changes - **docs**: Documentation update or addition - **feat**: Introduces a new feature or enhancement to the codebase - **fix**: Bug fix or error correction - **i18n**: Internationalization or localization changes - **perf**: Performance improvement - **refactor**: Code restructuring for better maintainability, readability, or scalability - **style**: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc.) - **test**: Adding missing tests or correcting existing tests - **WIP**: Work in progress, a temporary label for incomplete or ongoing work # Changelog Entry ### Description - Adds configurable `tools_timeout` and `tools_interval` parameters to ensure the client waits for the MCP server to be fully ready before listing tools. This prevents issues where the **tool list** is empty if the server is not ready, which can break API docs and OpenWebUI integration. I believe that every MCP server should provide tools—otherwise, there would be no point in building it. However, at the current stage, during the MCP connection process, some servers (when started via `session.initialize`) do not return any results from `list_tools` (instead, it returns an empty list []). It is **necessary to wait for a while** before calling `list_tools` to get the correct results. Based on my testing with an MCP server developed using `mcpsharp` (please forgive me for not being able to share the code due to security concerns), starting the MCP server takes some time. When I added print(tools) to the source code, I observed the following output: ``` Starting MCP OpenAPI Proxy on 0.0.0.0:8000 with command: cmd.exe /c C:\example.exe INFO: Started server process 36m43812 INFO: Waiting for application startup. TEST PRINT: Tools: [] INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit) ``` Since the tools have not yet been loaded, the API documentation (`localhost:8000/docs`) appears empty (at this point, OpenWebUI will hang), as shown below: ![image](https://github.com/user-attachments/assets/5a027e8e-24c5-4888-bdd5-f7c302001873) This improvement for MCPO serves as a temporary workaround. The ideal solution would be to address the issue on the MCP server side, ensuring that tools are available immediately after the server starts. However, this change provides a quick and efficient fix without impacting performance, and also adds a check to ensure MCP tools are present (otherwise, a `runtime error` is `raised`). ### Added - `tools_timeout` and `tools_interval` parameters, configurable via CLI or config, passed through app state. ex: `mcpo --port 8000 --tools-timeout 5 -- cmd.exe /c "C:\example.exe"` - Polling mechanism in `wait_list_tools` to wait for tools to be available. ### Changed ### Deprecated ### Removed ### Fixed - Fixes issue where tools list could be empty if the server is not fully started. ### Security ### Breaking Changes --- ### Additional Information ### Screenshots or Videos --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-18 21:12:26 +00:00