canhook-mcp

Remote MCP resource server for CanHook — inspect captured webhooks, diagnose relay delivery failures, replay requests, and manage endpoints from Claude (or any MCP agent) over an OAuth 2.1 connection.

• Public URL: https://canhook.com/mcp

• Transports: stdio + Streamable HTTP

• Auth: OAuth 2.1 (PKCE). The CanHook PHP app is the authorization server; this server validates bearer tokens by introspection.

Design decisions are in adr/; the SDK/transport spike is in docs/spike.md. The companion PHP app is jlugo32/canhook.

Setup

npm install
cp .env.example .env         # fill in DB (read-only user), INTROSPECTION_SECRET, INTERNAL_API_SECRET
npm run build

Related MCP server: webhook-ai-mcp

Run

# HTTP (production, reverse-proxied by OLS as https://canhook.com/mcp):
node dist/index.js
# or via PM2:
pm2 start ecosystem.config.cjs

# stdio (local/CLI, single user): set CANHOOK_TOKEN to a valid access token
CANHOOK_TOKEN=<access_token> node dist/index.js --stdio

Deploy

The server is a long-running Node process, not static files. Keep it out of the web docroot and reverse-proxy /mcp to it.

git pull && npm run build && pm2 reload canhook-mcp

Tools

Write tools and replay route through the CanHook PHP internal API, so the SSRF guard and plan limits are enforced in one place. diagnose_endpoint returns a structured diagnosis (success rate, failures grouped by plain-language cause, top failing destinations, primary diagnosis) an agent can explain to the user.

Verification

verify/run.sh drives 12 checks against a live local stack (PHP + Node) — OAuth discovery, PKCE flow, introspection, read/write tools, scope enforcement, IDOR, SSRF-through-MCP, diagnose, refresh rotation, unauthenticated rejection, and the key tripwire.

npm test               # unit tests (vitest)
npm run conformance    # MCP conformance suite vs conformance-baseline.yml (Node >= 22)

License

MIT — see LICENSE.