From 5c13d04f95df825d853ad3d9213c17451d8da621 Mon Sep 17 00:00:00 2001 From: Azimuth Date: Sun, 28 Jun 2026 02:56:55 -0700 Subject: [PATCH 1/2] feat(mcpproxy): add Exa Websets upstream via mcp-remote - Add Websets MCP server config pointing to https://websetsmcp.exa.ai/mcp - Use EXA_API_KEY from 1Password via env var reference - Update docs to reflect Exa search + Websets as upstreams - Update smoke test steps to include Websets tool discovery --- config/mcpproxy.seed.json | 16 +++++++++++++++- docs/2026-06-02-mcpproxy-gateway/README.md | 21 ++++++++++++--------- docs/CHANGELOG.md | 2 ++ docs/NOTES.md | 10 ++++++++++ 4 files changed, 39 insertions(+), 10 deletions(-) diff --git a/config/mcpproxy.seed.json b/config/mcpproxy.seed.json index 7d9f0e7..58e3fdf 100644 --- a/config/mcpproxy.seed.json +++ b/config/mcpproxy.seed.json @@ -23,6 +23,20 @@ "skip_quarantine": true, "enabled": true }, + { + "name": "websets", + "protocol": "stdio", + "command": "sh", + "args": [ + "-lc", + "exec npx -y mcp-remote \"https://websetsmcp.exa.ai/mcp\"" + ], + "env": { + "EXA_API_KEY": "${env:EXA_API_KEY}" + }, + "skip_quarantine": true, + "enabled": true + }, { "name": "fastmail", "url": "https://api.fastmail.com/mcp", @@ -39,4 +53,4 @@ "enabled": true } ] -} +} \ No newline at end of file diff --git a/docs/2026-06-02-mcpproxy-gateway/README.md b/docs/2026-06-02-mcpproxy-gateway/README.md index badf65c..53573a2 100644 --- a/docs/2026-06-02-mcpproxy-gateway/README.md +++ b/docs/2026-06-02-mcpproxy-gateway/README.md @@ -6,8 +6,9 @@ MCPProxy is the shared gateway for standards-compliant stdio, HTTP, SSE, and Str servers. MCP-capable hosts connect to one downstream endpoint while MCPProxy manages upstream OAuth credentials separately. Models do not connect to MCP directly; their host application does. -Fastmail and Exa are the initial upstreams imported from existing client configs. Client wiring is -deliberately deferred until the gateway passes its local and private-HTTPS smoke tests. +Fastmail, Exa search, and Exa Websets are the initial upstreams imported from existing client +configs and Exa's hosted Websets MCP setup. Client wiring is deliberately deferred until the gateway +passes its local and private-HTTPS smoke tests. ## Network and authentication @@ -22,8 +23,8 @@ Authentication has two separate boundaries: - `MCPPROXY_API_KEY` is the administrative secret rendered from `op://clankers/mcpproxy-admin/password`. -- `EXA_API_KEY` is rendered from `op://clankers/exa/password` and used only by the Exa stdio - upstream process. +- `EXA_API_KEY` is rendered from `op://clankers/exa/password` and used only by the Exa search and + Websets upstream processes. - MCP clients use a scoped agent token generated by MCPProxy and stored at `op://clankers/mcpproxy-agents/password`. - Fastmail receives only MCPProxy's OAuth access token. Downstream bearer tokens are never passed @@ -75,11 +76,13 @@ downstream token state together. 1. Confirm an unauthenticated MCP request returns `401`. 2. Complete Fastmail OAuth and verify `just mcpproxy-auth-status`. -3. Confirm Exa tools are discovered after `npx` installs `exa-mcp-server@3.2.1`. -4. Generate and store the scoped agent token. -5. Run authenticated `initialize` and `tools/list` requests through local and private HTTPS routes. -6. Call a harmless Fastmail read tool, restart `mcpproxy`, and repeat the read call. -7. Confirm `/ui/` and `/api/v1/status` return `404` through Caddy and port `3130` is absent from the +3. Confirm Exa search tools are discovered after `npx` installs `exa-mcp-server@3.2.1`. +4. Confirm Exa Websets tools are discovered after `npx` installs `mcp-remote` and connects to + `https://websetsmcp.exa.ai/mcp`. +5. Generate and store the scoped agent token. +6. Run authenticated `initialize` and `tools/list` requests through local and private HTTPS routes. +7. Call a harmless Fastmail read tool, restart `mcpproxy`, and repeat the read call. +8. Confirm `/ui/` and `/api/v1/status` return `404` through Caddy and port `3130` is absent from the LAN interface. The previous LiteLLM Fastmail experiment stays isolated on its existing POC branch. Remove the diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 8aaf198..b5e0d67 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -31,6 +31,8 @@ Recipes: `just oc-build` / `oc-up` / `oc-logs` / `ab-logs`. Caddy routes: `openclaw.dev.ankitson.com` → gateway, `agentbrowser.dev.ankitson.com` → noVNC. See [`NOTES.md`](NOTES.md). ## MCPProxy gateway (2026-06-02) +- Added the Exa Websets MCP upstream as `websets`, using Exa's hosted Websets endpoint via + `mcp-remote` and the existing `EXA_API_KEY` secret injection. - Added the Exa stdio MCP server from live Claude/Pi client configs to the MCPProxy upstream seed, using `EXA_API_KEY` from 1Password. - Added a host-networked `mcpproxy` service backed by the shared `ankit/mcpproxy:0.35.0` image. diff --git a/docs/NOTES.md b/docs/NOTES.md index b49a87a..1d6ff01 100644 --- a/docs/NOTES.md +++ b/docs/NOTES.md @@ -73,3 +73,13 @@ contract, and pending work. Full detail: - **Rollout**: complete Fastmail authorization in a browser running on the devserver host, generate the shared downstream agent token, store it in 1Password, then smoke-test before wiring clients. See [`docs/2026-06-02-mcpproxy-gateway/README.md`](2026-06-02-mcpproxy-gateway/README.md). + +## 2026-06-04 - Exa Websets MCP upstream +- **Goal**: add Exa Websets to the shared MCPProxy gateway alongside the existing Exa search + upstream. +- **Decision**: use Exa's hosted Websets MCP endpoint through `npx -y mcp-remote` so the Exa API key + stays in the process environment as `${env:EXA_API_KEY}` instead of being stored literally in the + endpoint URL. +- **Live config**: because `config/mcpproxy.seed.json` is seed-only after first boot, add or update + the live `websets` upstream in `/data/mcp_config.json` with the MCPProxy CLI when deploying this + change to an already-initialized volume. From 8c54da3427d0c5b76347566085d9b0d0c48826d5 Mon Sep 17 00:00:00 2001 From: Azimuth Date: Sun, 28 Jun 2026 03:02:18 -0700 Subject: [PATCH 2/2] fix(mcpproxy): pass Websets key via env expansion --- config/mcpproxy.seed.json | 2 +- docs/2026-06-02-mcpproxy-gateway/README.md | 2 +- docs/NOTES.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/config/mcpproxy.seed.json b/config/mcpproxy.seed.json index 58e3fdf..edb5c5f 100644 --- a/config/mcpproxy.seed.json +++ b/config/mcpproxy.seed.json @@ -29,7 +29,7 @@ "command": "sh", "args": [ "-lc", - "exec npx -y mcp-remote \"https://websetsmcp.exa.ai/mcp\"" + "exec npx -y mcp-remote \"https://websetsmcp.exa.ai/mcp?exaApiKey=${EXA_API_KEY}\"" ], "env": { "EXA_API_KEY": "${env:EXA_API_KEY}" diff --git a/docs/2026-06-02-mcpproxy-gateway/README.md b/docs/2026-06-02-mcpproxy-gateway/README.md index 53573a2..b6e121a 100644 --- a/docs/2026-06-02-mcpproxy-gateway/README.md +++ b/docs/2026-06-02-mcpproxy-gateway/README.md @@ -78,7 +78,7 @@ downstream token state together. 2. Complete Fastmail OAuth and verify `just mcpproxy-auth-status`. 3. Confirm Exa search tools are discovered after `npx` installs `exa-mcp-server@3.2.1`. 4. Confirm Exa Websets tools are discovered after `npx` installs `mcp-remote` and connects to - `https://websetsmcp.exa.ai/mcp`. + Exa's hosted Websets endpoint with the key supplied from `EXA_API_KEY` at runtime. 5. Generate and store the scoped agent token. 6. Run authenticated `initialize` and `tools/list` requests through local and private HTTPS routes. 7. Call a harmless Fastmail read tool, restart `mcpproxy`, and repeat the read call. diff --git a/docs/NOTES.md b/docs/NOTES.md index 1d6ff01..2333031 100644 --- a/docs/NOTES.md +++ b/docs/NOTES.md @@ -77,9 +77,9 @@ contract, and pending work. Full detail: ## 2026-06-04 - Exa Websets MCP upstream - **Goal**: add Exa Websets to the shared MCPProxy gateway alongside the existing Exa search upstream. -- **Decision**: use Exa's hosted Websets MCP endpoint through `npx -y mcp-remote` so the Exa API key - stays in the process environment as `${env:EXA_API_KEY}` instead of being stored literally in the - endpoint URL. +- **Decision**: use Exa's hosted Websets MCP endpoint through `npx -y mcp-remote` and expand + `EXA_API_KEY` from the process environment at runtime, so the seed config never stores a literal + key. - **Live config**: because `config/mcpproxy.seed.json` is seed-only after first boot, add or update the live `websets` upstream in `/data/mcp_config.json` with the MCPProxy CLI when deploying this change to an already-initialized volume.