Hub MCP Proxy

PodWarden Hub acts as an MCP proxy between your AI client and your PodWarden instance. Instead of connecting directly to your instance, your AI client connects to Hub. Hub routes tool calls through a secure WebSocket tunnel to your instance.

How it works

1. PodWarden opens an outbound tunnel — Your instance connects to Hub via WebSocket. The connection is outbound, so no ports need to be opened.
2. AI client connects to Hub — You point Claude, Cursor, or any MCP client at Hub's MCP endpoint. Interactive clients sign in with OAuth and name the instance in the URL; other clients present a personal access token (pwp_...) that already carries its instance.
3. Hub routes tool calls — When the AI calls a tool, Hub forwards the request through the tunnel to your instance. The tool executes locally and the result flows back.
4. Everything is logged — Every tool call through the tunnel appears in PodWarden's MCP Activity Log.

Setting up the tunnel

1. Connect to Hub

If you haven't already, connect your PodWarden instance to Hub:

1. Go to Settings > Hub
2. Enter the Hub URL (https://apps.podwarden.com)
3. Enter your instance key — the pwh_ key that connects a Core to Hub (create one in Hub Dashboard > API Keys)
4. Click Test Connection then Save

2. Enable the tunnel

1. Go to Settings > MCP
2. Find the Hub MCP Tunnel section (appears when Hub is configured)
3. Toggle Enable Tunnel on

PodWarden opens a persistent WebSocket connection to Hub. You can verify the connection in Hub Dashboard > MCP — your instance should appear as "Connected".

3. Set the access level

In the same MCP settings page, under MCP Access Level, choose:

The access level controls which tools are available through both direct MCP connections and the Hub tunnel. Changing the access level automatically reconnects the tunnel to update the available tool list — no restart needed.

Connecting your AI client

There are two ways to authenticate, and each has its own endpoint.

OAuth (interactive clients)

Endpoint: https://mcp.podwarden.com/<instance-uuid>

Sign in with your PodWarden Hub account — no credential to paste. The instance UUID in the path says which Core the connection talks to: one connection addresses one instance. If you run several Cores, make one connection per Core.

Personal access token

Endpoint: https://mcp.podwarden.com/mcp (no path segment)

Auth: A personal access token (pwp_...) as a Bearer token.

Mint the token in Hub Dashboard > MCP access — click Connect an AI client on the Core you want, choose Access token, and name it. It is scoped to exactly one instance and recorded against you, so the token already carries its instance — that is why this endpoint takes no path segment. Tokens can also be minted and revoked on Hub Dashboard > API Keys.

In the Access tokens table on that page, rotating a token mints a replacement and, by default, leaves both working for a grace window (2 hours, up to 24) so you can update the client before the old token stops — choose 0h to purge the old one immediately instead. You can rotate only a token you minted yourself; an organization admin can revoke anyone's.

Where to get the finished configuration

Hub Dashboard > MCP access builds both of the above for you. Each connected Core is a card carrying its own address; Connect an AI client opens a dialog that writes the config block with the real UUID — and, if you mint a token there, the real secret — already substituted. See Client Configuration for the same configurations written out.

Available tools

Hub exposes a slim facade of six tools. Your instance's own tools are reached through call_instance_tool rather than being listed individually.

A connection authenticated by a personal access token gets the first four. Organization memory is a shared human workspace, and a long-lived agent token writing notes under its minter's name is not a default worth having — so the memory tools are reserved for OAuth sessions. Tools that require a live human at a browser, such as node access grants, are filtered out of find's results for a token connection and are refused if called anyway.

Privacy and security

• Outbound only — Hub cannot reach into your network unless you explicitly enable the tunnel.
• Opt-in — The tunnel is disabled by default.
• Access control — You choose read-only or full access on the Core, which decides which tools the tunnel exposes at all.
• A token can never outreach its minter — A personal access token is a delegation. No role or permission snapshot is captured on it: a token carries no catalog or platform authority at all, whatever its minter holds. Its organization membership is re-checked on every call, so removing the minter from the organization stops the token immediately, and deleting their user account deletes the token with it.
• The UUID is an address, not a permission — Putting an instance UUID in the URL only says which instance you mean. Organization membership is checked against the authenticated session on every call, and a UUID belonging to another organization is refused.
• Attributable — A personal access token is recorded against the user who minted it, so calls made with it trace back to a named human.
• Audit trail — Every tool call is logged. Entries show "Hub Tunnel" as the token source.
• Disable anytime — Toggle the tunnel off to immediately cut the connection.

Direct vs. Hub proxy comparison