Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kataven.ai/llms.txt

Use this file to discover all available pages before exploring further.

A few MCP clients — ChatGPT, Claude.ai web, n8n — only accept remote MCP HTTPS URLs, not local stdio. The Kataven MCP server is stdio-only today, so you need a tunnel that exposes the local server publicly. This page is the recipe.
Direct stdio clients (Claude Desktop, Cursor, Windsurf, Zed, VS Code, JetBrains, Warp, Goose, Raycast) don’t need a tunnel — they spawn kataven-mcp as a local subprocess. Skip this page and go to your client’s setup guide.

​
What you need

  • The kataven-mcp binary installed (pip install kataven-mcp). Full install: Install →.
  • An sk_live_ API key minted at hub.kataven.ai/settings → API Keys.
  • A tunneling tool. We’ll use ngrok below; alternatives in Stable URLs.
  • supergateway — a small npm package that bridges stdio MCP servers to SSE.

​
The 30-second recipe

# 1. Install supergateway (one-time)
npm install -g supergateway

# 2. Start kataven-mcp behind a local SSE endpoint on port 8080
KATAVEN_API_KEY=sk_live_acme_... \
  supergateway --stdio "kataven-mcp" --port 8080

# 3. In a second terminal, expose port 8080 over HTTPS
ngrok http 8080
# → forwarding https://abc123.ngrok.app -> http://localhost:8080
Your remote MCP URL is https://abc123.ngrok.app/sse — paste this into your AI client’s MCP config: That’s it. The AI client makes HTTPS requests to the ngrok URL, ngrok proxies to your local supergateway, supergateway pipes through to the stdio kataven-mcp subprocess. 
AI client (ChatGPT/Claude.ai/n8n)
   │  HTTPS SSE
   ▼
ngrok https://abc123.ngrok.app
   │  HTTP
   ▼
localhost:8080  (supergateway --stdio kataven-mcp)
   │  stdio pipe
   ▼
kataven-mcp subprocess
   │  HTTPS to api.kataven.ai
   ▼
Kataven Hub API

​
Stable URLs

Free ngrok URLs change every session and idle out. For day-to-day use, three better options:

​
Option A — pinned ngrok subdomain (paid)

ngrok http --domain=kataven.your-handle.ngrok.app 8080
URL stays the same across restarts. Requires an ngrok paid plan.

​
Option B — Cloudflare Tunnel (free, stable)

brew install cloudflared      # macOS; on Linux/Windows see Cloudflare's docs
cloudflared tunnel --url http://localhost:8080
# → https://random-words.trycloudflare.com
Quick mode gives a stable URL per machine without a Cloudflare account. For a permanent named tunnel, follow Cloudflare’s tunnel docs — this is the option we use internally.

​
Option C — Tailscale Funnel

If you’re already running Tailscale on the machine: 
tailscale serve --bg http://localhost:8080
tailscale funnel --bg 8080
Stable Tailscale-issued HTTPS URL, only your tailnet members can reach it (more private than ngrok).

​
Running supergateway as a service

For a tunnel that survives reboots / terminal closes, daemonize supergateway. macOS launchd example: 
<!-- ~/Library/LaunchAgents/ai.kataven.mcp-tunnel.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>           <string>ai.kataven.mcp-tunnel</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/supergateway</string>
    <string>--stdio</string><string>kataven-mcp</string>
    <string>--port</string><string>8080</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>KATAVEN_API_KEY</key><string>sk_live_acme_...</string>
  </dict>
  <key>RunAtLoad</key>      <true/>
  <key>KeepAlive</key>      <true/>
  <key>StandardErrorPath</key><string>/tmp/kataven-mcp-tunnel.err.log</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/ai.kataven.mcp-tunnel.plist
Pair with a Cloudflare Named Tunnel (also daemonized via cloudflared service install) for a fully background setup.

​
Security tradeoffs

  • Anyone with the public URL can call kataven-mcp during the session, gated only by the KATAVEN_API_KEY baked into the supergateway environment. The AI vendor (OpenAI, Anthropic, n8n) sees the URL but not the API key.
  • Random ngrok URLs are obscurity, not security. A determined attacker scanning subdomains could find them, though ephemeral free URLs make this impractical for short sessions. For team / production use, use a Cloudflare Named Tunnel with Cloudflare Access in front of it (free SSO gate) — see Cloudflare’s docs.
  • Shut the tunnel down when you’re not using it. kill the supergateway and ngrok processes when the session ends, or lean on KeepAlive: false in launchd.
Full risk model: Security.

​
What’s next: hosted remote MCP

We’re working on a hosted Kataven MCP endpoint at mcp.kataven.ai — once shipped, you’ll skip the tunnel entirely and paste a Kataven-managed URL into ChatGPT / Claude.ai web / n8n directly. This page will update with the new pattern when it ships.

​
See also