π Open WebUI Integration
Overviewβ
Open WebUI v0.6+ supports seamless integration with external tools via the OpenAPI servers β meaning you can easily extend your LLM workflows using custom or community-powered tool servers π§°.
In this guide, you'll learn how to launch an OpenAPI-compatible tool server and connect it to Open WebUI through the intuitive user interface. Letβs get started! π
Step 1: Launch an OpenAPI Tool Serverβ
To begin, you'll need to start one of the reference tool servers available in the openapi-servers repo. For quick testing, weβll use the time tool server as an example.
π οΈ Example: Starting the time
server locally
git clone https://github.com/open-webui/openapi-servers
cd openapi-servers
# Navigate to the time server
cd servers/time
# Install required dependencies
pip install -r requirements.txt
# Start the server
uvicorn main:app --host 0.0.0.0 --reload
Once running, this will host a local OpenAPI server at http://localhost:8000, which you can point Open WebUI to.
Step 2: Connect Tool Server in Open WebUIβ
Next, connect your running tool server to Open WebUI:
- Open WebUI in your browser.
- Open βοΈβ―Settings.
- Click on β Tools to add a new tool server.
- Enter the URL where your OpenAPI tool server is running (e.g., http://localhost:8000).
- Click "Save".
π§βπ» User Tool Servers vs. π οΈ Global Tool Serversβ
There are two ways to register tool servers in Open WebUI:
1. User Tool Servers (added via regular Settings)β
- Only accessible to the user who registered the tool server.
- The connection is made directly from the browser (client-side) by the user.
- Perfect for personal workflows or when testing custom/local tools.
2. Global Tool Servers (added via Admin Settings)β
Admins can manage shared tool servers available to all or selected users across the entire deployment:
- Go to π οΈ Admin Settings > Tools.
- Add the tool server URL just as you would in user settings.
- These tools are treated similarly to Open WebUIβs built-in tools.
Main Difference: Where Are Requests Made From?β
The primary distinction between User Tool Servers and Global Tool Servers is where the API connection and requests are actually made:
-
User Tool Servers
- Requests to the tool server are performed directly from your browser (the client).
- This means you can safely connect to localhost URLs (like
http://localhost:8000
)βeven exposing private or development-only endpoints such as your local filesystem or dev toolsβwithout risking exposure to the wider internet or other users. - Your connection is isolated; only your browser can access that tool server.
-
Global Tool Servers
- Requests are sent from the Open WebUI backend/server (not your browser).
- The backend must be able to reach the tool server URL you specifyβso
localhost
means the backend server's localhost, not your computer's. - Use this for sharing tools with other users across the deployment, but be mindful: since the backend makes the requests, you cannot access your personal local resources (like your own filesystem) through this method.
- Think security! Only expose remote/global endpoints that are safe and meant to be accessed by multiple users.
Summary Table:
Tool Server Type | Request Origin | Use Localhost? | Use Case Example |
---|---|---|---|
User Tool Server | User's Browser (Client-side) | Yes (private to you) | Personal tools, local dev/testing |
Global Tool Server | Open WebUI Backend (Server-side) | No (unless running on the backend itself) | Team/shared tools, enterprise integrations |
User Tool Servers are best for personal or experimental tools, especially those running on your own machine, while Global Tool Servers are ideal for production or shared environments where everyone needs access to the same tools.
π Optional: Using a Config File with mcpoβ
If you're running multiple tools through mcpo using a config file, take note:
π§© Each tool is mounted under its own unique path!
For example, if youβre using memory and time tools simultaneously through mcpo, theyβll each be available at a distinct route:
This means:
- When connecting a tool in Open WebUI, you must enter the full route to that specific tool β do NOT enter just the root URL (http://localhost:8000).
- Add each tool individually in Open WebUI Settings using their respective subpath URLs.
β Good:
http://localhost:8000/time
http://localhost:8000/memory
π« Not valid:
This ensures Open WebUI recognizes and communicates with each tool server correctly.
Step 3: Confirm Your Tool Server Is Connected β β
Once your tool server is successfully connected, Open WebUI will display a π tool server indicator directly in the message input area:
π You'll now see this icon below the input box:
Clicking this icon opens a popup where you can:
- View connected tool server information
- See which tools are available and which server they're provided by
- Debug or disconnect any tool if needed
π Hereβs what the tool information modal looks like:
π οΈ Global Tool Servers Look Different β And Are Hidden by Default!β
If you've connected a Global Tool Server (i.e., one thatβs admin-configured), it will not appear automatically in the input area like user tool servers do.
Instead:
- Global tools are hidden by default and must be explicitly activated per user.
- To enable them, you'll need to click on the β button in the message input area (bottom left of the chat box), and manually toggle on the specific global tool(s) you want to use.
Hereβs what that looks like:
β οΈ Important Notes for Global Tool Servers:
- They will not show up in the tool indicator popup until enabled from the β menu.
- Each global tool must be individually toggled on to become active inside your current chat.
- Once toggled on, they function the same way as user tools.
- Admins can control access to global tools via role-based permissions.
This is ideal for team setups or shared environments, where commonly-used tools (e.g. document search, memory, or web lookup) should be centrally accessible by multiple users.
(Optional) Step 4: Use "Native" Function Calling (ReACT-style) Tool Use π§ β
For this to work effectively, your selected model must support native tool calling. Some local models claim support but often produce poor results. We strongly recommend using GPT-4o or another OpenAI model that supports function calling natively for the best experience.
Want to enable ReACT-style (Reasoning + Acting) native function calls directly inside your conversations? You can switch Open WebUI to use native function calling.
β³οΈ How to enable native function calling:
- Open the chat window.
- Go to βοΈβ―Chat Controls > Advanced Params.
- Change the Function Calling parameter from
Default
toNative
.
Need More Tools? Explore & Expand! π§±β
The openapi-servers repo includes a variety of useful reference servers:
- π Filesystem access
- π§ Memory & knowledge graphs
- ποΈ Git repo browsing
- π Web search (WIP)
- π’οΈ Database querying (WIP)
You can run any of these in the same way and connect them to Open WebUI by repeating the steps above.
Troubleshooting & Tips π§©β
- β Not connecting? Make sure the URL is correct and accessible from the browser used to run Open WebUI.
- π If you're using remote servers, check firewalls and HTTPS configs!
- π To make servers persist, consider deploying them in Docker or with system services.
Need help? Visit the π Discussions page or open an issue.