WorkBuddy installation and usage

Camofox Web Search integrates with Tencent WorkBuddy through a bundled local stdio bridge. The bridge reads the API key from the WorkBuddy process and connects to the Gateway's Streamable HTTP MCP endpoint, because WorkBuddy 5.3.8 supports only static HTTP connector headers and does not expand ${WEB_SEARCH_API_KEY} there. WorkBuddy receives the read-only web_search and web_fetch tools while browser traffic, authentication, provider fallback, and SSRF protection stay in your self-hosted Gateway.

WorkBuddy task → local stdio bridge → authenticated /mcp → Camofox Web Search → browser/providers

Five-minute tutorial

Verify that the Gateway is ready with curl -fsS https://search.example.com/readyz.
Install the CLI and run install workbuddy in user or project scope.
Expose WEB_SEARCH_API_KEY to the WorkBuddy desktop process and fully restart WorkBuddy.
Open Plugins → MCP servers, approve camofox_web, and confirm that it is green.
Run doctor workbuddy --live, then ask WorkBuddy to call both Camofox tools.

The detailed commands and platform-specific instructions follow below.

Requirements

A running Camofox Web Search deployment and its public WEB_SEARCH_API_KEY.
WorkBuddy 5.3.8. The integration is tested with the macOS ARM64 desktop client; newer releases should be rechecked with doctor after upgrading.
Node.js 22 or newer for the camofox-web-search configuration CLI.

Verify the Gateway before changing WorkBuddy:

curl -fsS https://search.example.com/readyz

Install

Install the CLI, make the public key available to the current shell, and configure either user or project scope:

npm install -g camofox-web-search
export WEB_SEARCH_API_KEY="<copy securely from the server .env>"

camofox-web-search install workbuddy \
  --endpoint https://search.example.com \
  --scope user

User scope writes ~/.workbuddy/mcp.json and is available to every WorkBuddy project. Project scope writes .workbuddy/mcp.json below the current directory:

camofox-web-search install workbuddy \
  --endpoint https://search.example.com \
  --scope project

The managed entry contains absolute paths to the Node.js executable and the bundled workbuddy-bridge.js, plus the non-secret Gateway endpoint. The token and Authorization header are never written to the WorkBuddy configuration. Re-run the installer after moving or replacing the Node.js or global camofox-web-search installation; use --force when intentionally refreshing an older managed path.

To audit the generated entry without printing a secret, inspect the file or compare it with the checked-in WorkBuddy example:

sed -n '1,120p' ~/.workbuddy/mcp.json

Make the key available to WorkBuddy

Desktop applications do not necessarily inherit variables exported by an interactive shell. On macOS, fully quit WorkBuddy, pass the variable to the per-user launch environment, and reopen the application:

launchctl setenv WEB_SEARCH_API_KEY "$WEB_SEARCH_API_KEY"
open -a WorkBuddy

Remove it from the launch environment when no longer needed:

launchctl unsetenv WEB_SEARCH_API_KEY

On Windows, set a user environment variable and restart WorkBuddy:

[Environment]::SetEnvironmentVariable("WEB_SEARCH_API_KEY", "<your-public-gateway-key>", "User")

Do not replace the environment-variable reference with a real token in a tracked file.

Trust and use the connector

In WorkBuddy, open Plugins → MCP servers. Approve the trust prompt for camofox_web if one appears and confirm its status is green. Then ask WorkBuddy to use the Camofox tools explicitly, for example:

Use camofox_web web_search to find the Model Context Protocol specification, then use camofox_web web_fetch to read the primary result and cite it.

This wording distinguishes the connector from WorkBuddy's built-in Web Search skill during acceptance testing.

Successful acceptance means the task shows calls to both camofox_web_web_search and camofox_web_web_fetch; a normal prose answer without those tool calls does not prove that the integration is working.

Diagnose

Run the doctor in the same scope used for installation:

camofox-web-search doctor workbuddy \
  --endpoint https://search.example.com \
  --scope user \
  --live

The command checks the local WorkBuddy bridge entry, environment-variable availability, transport security, Gateway health, the exact MCP tool set, and a real search.

Acceptance checklist

doctor reports PASS for configuration, environment, transport, health, MCP tools, and live search.
WorkBuddy shows camofox_web as connected with exactly web_search and web_fetch.
The explicit test prompt produces real calls to both connector tools.
No API key or Authorization header appears in ~/.workbuddy/mcp.json, .workbuddy/mcp.json, screenshots, or logs.

Troubleshooting

Symptom	Check
Connector is red	Confirm the configured Node.js and bridge paths still exist, verify the endpoint, restart WorkBuddy after setting the environment variable, and inspect the WorkBuddy MCP details.
`401 unauthorized`	Confirm WorkBuddy inherited the same `WEB_SEARCH_API_KEY` generated by the server. Never paste the key into a tracked configuration.
Tools are absent	Approve the connector trust prompt, confirm `camofox_web` is enabled, and start a new task after restarting WorkBuddy.
Remote connection fails	Remote endpoints must use HTTPS. If a proxy is configured, exclude the Gateway host from interception that breaks MCP streaming.
Project connector is missing	Open the same directory that contains `.workbuddy/mcp.json`; otherwise install with `--scope user`.

Uninstall

Remove only the managed camofox_web entry while preserving other WorkBuddy connectors:

camofox-web-search uninstall workbuddy \
  --endpoint https://search.example.com \
  --scope user

Restart WorkBuddy after uninstalling. Uninstalling does not remove WEB_SEARCH_API_KEY from the operating-system environment.