feat(mcp): native OpenClaw MCP via credential-injecting proxy by clemenshelm · Pull Request #298 · heypinchy/pinchy

clemenshelm · 2026-05-07T05:11:30Z

Connect any MCP server to Pinchy through OpenClaw's native mcp.servers, with third-party tokens kept off disk behind a credential-injecting reverse proxy, per-agent tool gating, and a full audit trail.

How it works

OpenClaw's native mcp.servers.<key> points at a Pinchy proxy (/api/internal/mcp-proxy/<connectionId>), not the third-party server. The proxy authenticates the gateway bootstrap token, decrypts the real bearer token in memory, injects Authorization: Bearer <token>, and streams the request through. So:

No third-party token ever lands in openclaw.json — it lives encrypted in Pinchy's DB and only in this process's memory.
Token rotation / adding a connection needs no OpenClaw restart.
Per-agent gating rides the standard agents.list[].tools.allow (tool name = mcpServerKey(connId)__<tool>).
SSRF guard re-validates the upstream URL on every request (opt-out ALLOW_PRIVATE_URLS=1 for self-hosted internal servers).

Best-of-both-worlds re-integration

This branch was rebuilt from the ground up on current main: the proven MCP substance (proxy, native emission, E2E) is kept, while every parallel invention was replaced with main's now-existing generic mechanisms.

Permissions use main's generic agent_connection_permissions (model="mcp", operation=<toolName>) — the dedicated agent_mcp_tool_permissions table is gone.
Skills: each connection generates a dynamic per-connection skill from the agent's granted tools, with a safety block telling the model that server responses are data, not instructions. Nothing user-authored; it appears and disappears with the grants.
Feature flag: one server-side PINCHY_MCP_ENABLED, read at runtime and passed to the client as a prop (no NEXT_PUBLIC_ build-time inline — that would freeze the flag into a prebuilt image).

Presets & templates

Eight presets (GitHub, Linear, Atlassian, Stripe, Cloudflare, Intercom, HighLevel, and a generic "any MCP server" — the load-bearing one). Two agent templates (GitHub PR Reviewer, Linear Triage) with per-preset availability gating and auto-granting of their recommended tools on creation.

Verification

Every gate green, and the MCP E2E ran live against a real Docker stack: 10/10 — connection create + tool discovery, grants, per-tool gating, drift rejection, audit rows, the full round-trip dispatch (trigger → OpenClaw → proxy → mock → audit), and token rotation with no restart.

Docs added under guides/, reference/, and explanation/ (including the security-boundary write-up).

_{Rebased onto current main (119 commits); migration regenerated against the new baseline. One security fix surfaced by the rebase itself: main's credential-form drift guard (#743) caught two MCP forms that defaulted to a GET submit, which would have leaked the token into the URL — now method="post". Contains one deliberate, label-authorized test removal (dead toolPrefix field).}

Six CI failures from PR #298, all rooted in three issues: 1. **PUT body shape regression.** The unified discriminated-union endpoint `[{kind:"odoo"|"mcp", connectionId, ...}]` replaced the legacy `{connectionId, permissions}` shape. The Odoo `setAgentPermissions` helper, the email E2E spec, and the odoo-agent-chat response parser were still on the old shape. Updated all three to the new shape. 2. **Sync eager-cascaded permissions instead of letting drift surface at GET time.** The MCP E2E spec explicitly asserts "permission row still exists — drift is detected at read time, not eagerly deleted by sync" but the implementation cascade-deleted in the sync transaction. Removed the cascade; drift detection in `agents/[id]/integrations` GET now finds the stale rows and reports them. Added a defensive filter in `openclaw-config/build.ts` so drifted permissions aren't emitted into the runtime config. Also wired up a failure-audit + 502 path for `listMcpTools` errors (review feedback). `toolPrefix` now resolves from the preset registry rather than a stale `data.toolPrefix` field. 3. **Test infrastructure misses for the new table + general E2E picking up MCP specs.** Added `agent_mcp_tool_permissions` to the integration-suite truncate list and excluded `e2e/mcp/**` from the general playwright config. Format-only: `prettier --write` on `mcp-gate.test.ts`. Verified locally: format check ✓, tsc ✓, lint 0 errors, 3881 vitest tests pass.

PR #298's UI refactor split the integration type picker out of the modal into a dedicated `/settings/integrations/new` page (commit 82475f1). The "Add Integration" button became a `<Link>`, not a modal trigger — but the Odoo wizard E2E tests still expected a dialog to open directly on click. The happy-path test timed out after 2 minutes waiting for a dialog that won't appear at the old URL. Update both Odoo wizard tests to follow the new flow: 1. Click the "Add Integration" link (now navigates) 2. Land on /settings/integrations/new 3. Click the Odoo tile — opens the wizard dialog with `initialType=odoo` so the connect step renders straight away 4. Resume the existing wizard flow Other E2E specs were checked — only odoo-wizard.spec.ts uses the Add-Integration click path; MCP / Email / Web Search specs all seed via REST so they're unaffected.