Open WebUI WorkPaper tool setup

May 27, 2026 · View on GitHub

Use this when Open WebUI should call spreadsheet tools, but the spreadsheet logic should stay in a formula-backed WorkPaper instead of an Excel browser session.

Open WebUI has three useful integration paths:

hosted OpenAPI tool server for the quickest no-bridge demo;
native MCP (Streamable HTTP) for an HTTP MCP endpoint;
mcpo when the tool server is a local stdio MCP process that needs to be exposed as an OpenAPI tool server.

Official Open WebUI references:

Fastest smoke test: hosted OpenAPI

Open WebUI's OpenAPI tool-server path can connect to ordinary HTTP JSON endpoints. For a no-bridge Bilig proof, add this tool server URL:

https://bilig.proompteng.ai/openapi/workpaper

If your Open WebUI build expects the explicit OpenAPI document URL, use:

https://bilig.proompteng.ai/openapi/workpaper/openapi.json

The hosted OpenAPI server exposes three stateless demo operations:

list_workpaper_sheets
read_workpaper_range
set_workpaper_cell_and_readback

Ask:

Use the Bilig WorkPaper OpenAPI tool. Call set_workpaper_cell_and_readback
with sheetName Inputs, address B3, value 0.4, and readbackRange Summary!A1:B3.
Return the before, after, restoredReadback, and checks object.

The important check is checks.readbackChanged === true and checks.restoredReadbackMatchesAfter === true. The hosted OpenAPI endpoint is request-local and does not persist a private workbook. Use the local mcpo bridge below when Open WebUI needs a writable project file.

Fastest smoke test: hosted Streamable HTTP

Open WebUI's native MCP path can connect to a Streamable HTTP server from Admin Settings -> External Tools with type MCP (Streamable HTTP).

For a quick Bilig proof, add this server URL:

https://bilig.proompteng.ai/mcp

Use Auth: None unless your deployment sits behind its own gateway token.

Then open a chat, enable the Bilig tool from the integrations/tools menu, and ask:

Use the Bilig WorkPaper tools. Call set_cell_contents_and_readback with
sheetName Inputs, address B3, value =0.4, and readbackRange Summary!A1:B3.
Return the proof object and say whether the dependent formula readback changed.

Expected tools:

list_sheets
read_range
read_cell
set_cell_contents
set_cell_contents_and_readback
get_cell_display_value
export_workpaper_document
validate_formula

The hosted endpoint is stateless and request-local. Use set_cell_contents_and_readback when Open WebUI needs a single call that writes an input and returns dependent formula readback before the request ends. The endpoint is good for verifying Open WebUI can discover and call the tools. It does not persist a private project workbook.

Persistent project file: mcpo bridge

Use mcpo when Open WebUI needs an OpenAPI tool server for a local stdio MCP process. This is the right shape when the WorkPaper JSON file lives on the host or in a container volume.

From the machine that can reach the WorkPaper file:

uvx mcpo --host 0.0.0.0 --port 8000 -- \
  npx -y --package @bilig/workpaper@latest \
    bilig-workpaper-mcp \
    --workpaper ./pricing.workpaper.json \
    --init-demo-workpaper \
    --writable

Open the generated tool docs:

http://localhost:8000/docs

Then add the tool server URL in Open WebUI. For a personal user tool, the URL can be:

http://localhost:8000

For a global tool server configured from the Open WebUI backend, remember that localhost means the Open WebUI backend container or host, not your laptop. When Open WebUI runs in Docker and the mcpo server is on the host, use:

http://host.docker.internal:8000

Native MCP versus mcpo

Path	Use when	URL to add
Hosted OpenAPI	Open WebUI should call ordinary HTTP tools without a bridge.	`https://bilig.proompteng.ai/openapi/workpaper`
Native MCP	Open WebUI can call a Streamable HTTP MCP endpoint directly.	`https://bilig.proompteng.ai/mcp`
mcpo	Open WebUI should call a local stdio MCP server through OpenAPI.	`http://localhost:8000` or `http://host.docker.internal:8000`

Start with hosted OpenAPI when you want the fewest moving parts in Open WebUI. Use native MCP when your deployment already prefers MCP. Use mcpo for a real writable WorkPaper file that must persist across turns or jobs.

Proof object to ask for

Ask the model to return a concrete proof instead of "the cell was updated":

{
  "editedCell": "Inputs!B3",
  "before": {
    "Summary!B2": "60000"
  },
  "after": {
    "Summary!B3": "96000"
  },
  "readbackRange": "Summary!A1:B3",
  "restoredReadbackMatchesAfter": true,
  "persistedDocumentBytes": 1000,
  "verified": true,
  "limitations": ["Hosted smoke endpoint is request-local.", "Use mcpo or local stdio for a private writable WorkPaper file."]
}

verified should only be true after a readback of the dependent formula output.

Troubleshooting

If Open WebUI says the MCP server failed to connect, check that the tool type is MCP (Streamable HTTP), not OpenAPI.
If using the hosted endpoint, leave auth set to None.
If using mcpo from Docker, replace localhost with host.docker.internal or the reachable host IP.
If global tools do not show in chat, enable the tool from the chat integrations/tools picker. Global tool servers can be hidden until enabled.
Use a model with native function calling for multi-step read/write/readback tool use.