AI Agents and Tunnel Automation: Inside the Pinggy MCP Server
IT
Quick answer
AI Agents & Tunnel Automation: MCP Servers, Pinggy & Claude : quick comparison answer
Choose the tunnel tool based on the network model: public HTTPS URLs for webhooks and demos, private mesh access for internal apps, and managed infrastructure when policy controls matter most.
Which tunnel tool is best for public webhook testing?
Use a public HTTPS localhost tunnel with stable URLs. InstaTunnel focuses on webhook testing, demos, OAuth callbacks, and MCP endpoint workflows.
When should I choose a private network tool instead?
Choose a private mesh or Zero Trust tool when every user and service should stay inside a controlled private network.
Developers running Claude Code, Cursor, Claude Desktop, or Windsurf as their primary interface increasingly want those agents to handle more than code generation — including standing up a public URL for a local dev server. Pinggy is one of the first tunneling vendors to formalize this with dedicated agent tooling: an Agent Skill and a standalone MCP server, both published under an early-access, experimental label. This piece walks through what each actually does, how to install them correctly (the config paths differ more than you’d expect between clients), and what the current security picture looks like once an agent can open a tunnel on its own.
Manual tunneling, and where the friction is
The baseline workflow hasn’t changed in years: run ssh -p 443 -R0:localhost:8000 free.pinggy.io (or the equivalent for ngrok, Cloudflare Tunnel, or whatever you use), copy the resulting URL, and paste it wherever it’s needed — a webhook dashboard, a Slack message, a .env file. When an AI coding agent is already driving the terminal, this is one more manual handoff between the agent’s context and yours.
The Model Context Protocol (MCP), which Anthropic released in late 2024, gives agents a standardized way to call external tools instead of shelling out to a CLI and parsing the output. An MCP setup has three parts: hosts (the agent applications — Claude Code, Cursor, Claude Desktop, Windsurf), clients (the protocol connection each host maintains), and servers (processes that expose a specific set of tools, resources, or prompts over that connection). Wrapping a tunneling client in an MCP server means the agent calls a tool like start_tunnel directly, gets back structured data (the public URL, tunnel ID, status), and never has to construct or parse a shell command.
Skill vs. MCP server: two different things
Pinggy ships two separate pieces of agent tooling, and it’s worth being precise about the difference, because the vendor’s own docs are:
| Skill | MCP server | |
|---|---|---|
| What it is | Packaged reference docs (SSH, CLI, SDK, every flag and tunnel type) that the agent reads | A running process exposing tunnel operations as callable tools |
| What the agent does with it | Reads the docs, then runs commands itself via ordinary terminal access | Calls tools directly — no command construction |
| Install | npx skills add https://pinggy.io | uvx-based config, per client |
Pinggy’s own guidance is to start with the skill if you want the agent to understand the tool, and add the MCP server only once you want it operating tunnels autonomously. The two can be installed independently or together, and the skill install works the same way across agents — the CLI detects the client and writes the skill files into its skills directory (~/.claude/skills/pinggy/ for Claude Code, for example).
The rest of this piece focuses on the MCP server, since that’s what enables the “tunnel without leaving the chat” behavior most people mean when they talk about agent-driven tunneling.
What the Pinggy MCP server actually exposes
The server is a Python package (requires Python 3.10+ and uv) published at github.com/Pinggy-io/pinggy_mcp. It’s explicitly flagged in its own README as experimental — “shared for early feedback, expect rough edges” — which is worth keeping in mind before wiring it into anything you depend on.
Once installed, it registers thirteen tools across four groups:
Authentication - authenticate — starts the OAuth2 device flow and returns a login URL - check_authentication — login status, account email, token expiry - get_profile — fetches your Pinggy account profile - logout — clears the stored session
Tunnels - start_tunnel — HTTP, TCP, TLS, or UDP, with optional IP allow-listing, header rewriting, and web debugger - stop_tunnel, list_tunnels, get_tunnel_info
File sharing - share_directory — exposes a local folder over WebDAV through a public Pinggy URL - stop_file_share, list_file_shares
Token management - add_token, remove_token, list_tokens, update_token — for attaching a specific Pinggy token (useful for reserved subdomains or custom domains) to a given port
You don’t call these directly; you ask in plain language (“expose port 3000,” “list my active tunnels,” “only allow traffic from 1.2.3.4”) and the agent picks the right tool. That part of the original framing was accurate — this genuinely does support HTTP/TCP/TLS/UDP tunnels and directory sharing over WebDAV, not just HTTP.
Authentication: this part checks out
The claim that Pinggy uses OAuth 2.0 Device Authorization Grant (RFC 8628) rather than pasted API tokens is correct. Saying “log in to Pinggy” triggers authenticate, which contacts the Pinggy backend and returns a URL; you approve it in a browser while the MCP server polls in the background, then stores and silently refreshes the session going forward. The session is written to ~/.config/pinggy-mcp/config.json (Linux/macOS) or %LOCALAPPDATA%\pinggy-mcp\config.json (Windows), chmod 600 on Unix. Saved tokens are optional and only needed for things OAuth doesn’t cover, like binding a specific reserved subdomain to a specific local port.
Installing it — corrected per client
This is where the original draft’s instructions had errors worth flagging, since a wrong config path is the difference between “it works” and “nothing shows up in the tool list.” Cursor and VS Code use different config locations and even different JSON schemas (mcpServers vs. servers), and conflating them, as an earlier version of these instructions did, will produce a config the intended client can’t read.
Claude Code — this is the simplest path; it’s a one-line CLI command, no manual file editing:
claude mcp add pinggy-mcp -- uvx --from git+https://github.com/Pinggy-io/pinggy_mcp.git pinggy-mcp
Verify with claude mcp list.
Claude Desktop — edit the config file directly: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json - Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"pinggy-mcp": {
"command": "uvx",
"args": ["--from", "git+https://github.com/Pinggy-io/pinggy_mcp.git", "pinggy-mcp"]
}
}
}
Restart the app; pinggy should appear in the MCP indicator below the input box.
Cursor — a different path from VS Code, despite both being editors: - Global: ~/.cursor/mcp.json - Per-project: .cursor/mcp.json in the project root
Same JSON shape as Claude Desktop, above.
VS Code — different again, and note the schema change (servers, not mcpServers, plus an explicit "type": "stdio"): - macOS/Linux: ~/.vscode/mcp.json - Windows: %APPDATA%\Code\User\mcp.json - Or .vscode/mcp.json for a workspace-scoped config
{
"servers": {
"pinggy-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/Pinggy-io/pinggy_mcp.git", "pinggy-mcp"]
}
}
}
Reload with Developer: Reload Window from the command palette.
Windsurf — edit ~/.codeium/windsurf/mcp_config.json with the same shape as the Claude Desktop config, then restart.
One naming inconsistency worth flagging for anyone browsing the repo: Pinggy’s own documentation site links to github.com/Pinggy-io/pinggy_mcp as canonical, but several code blocks inside that same repo’s README (the local-development clone instructions, notably) still reference an earlier path, github.com/abhimp/pinggy_mcp, from before the project moved under the Pinggy-io org. Both currently resolve via GitHub’s redirect, but use the Pinggy-io org path going forward.
What agent-driven tunneling looks like in practice
A representative (illustrative, not a documented vendor case study) workflow: you’re running a local dev server and want a client to see it. Instead of switching terminals, you ask your agent to start the server, expose it, and draft a message with the link. The agent runs the dev command, identifies the port, calls start_tunnel, gets back a public URL, and can reference that URL — plus whatever it knows about your recent commits — in the same context window it used to write the code. The mechanism is real (the tools exist and do this); treat any specific multi-step “and then it emails the client” chain as an example of what’s possible with an agent that also has terminal and file access, not a scripted Pinggy feature.
Webhook testing follows the same shape and is arguably the stronger use case: an agent that both writes a webhook handler and provisions the tunnel to test it against a live third-party service (Stripe, Shopify, GitHub) doesn’t need a human to bridge the two steps. It can call start_tunnel, register the resulting URL with whatever webhook-registration mechanism it has access to (the provider’s own CLI or API, via a separate tool call), then trigger a test event and check application logs. The exact orchestration depends on what other tools the agent has connected, not on Pinggy specifically.
How this compares to ngrok and Cloudflare
Pinggy isn’t the only tunneling vendor building for agents, and the approaches differ in what they’re optimizing for. ngrok’s primary agent-facing angle is the reverse of Pinggy’s: rather than an agent operating your ngrok account, ngrok’s documented pattern is using ngrok as a gateway that exposes an MCP server you’re running locally to a remote LLM platform, with identity and traffic-policy controls sitting in front of it — closer to an API gateway for MCP traffic than a tunnel-management skill. Separately, community-built MCP servers exist (via Composio and others) that let an agent manage an ngrok account’s tunnels and endpoints directly, comparable to what Pinggy ships natively, but these aren’t first-party ngrok tooling in the same way. Cloudflare bundles its MCP servers with Skills and slash commands through a Cloudflare Skills plugin, installable via the Claude Code plugin marketplace or the same npx skills add CLI Pinggy uses, but its support spans the broader Cloudflare One / Zero Trust platform rather than being tunnel-specific.
Security: what the built-in safeguards actually cover, and what they don’t
The original framing here undersold how much exposure exists industry-wide, so it’s worth separating what Pinggy’s design genuinely mitigates from the broader risk picture.
What’s real about Pinggy’s design: - Tunnels live inside the MCP server process. When the host application (Claude Code, Cursor, Claude Desktop) restarts, the server restarts, and every running tunnel dies with it — there’s no lingering background daemon. - OAuth device-flow authentication means the agent never handles a raw API token in plaintext. - Most MCP clients, including Cursor, gate tool execution behind an explicit approval step by default, so a start_tunnel call typically surfaces an approve/reject prompt rather than running silently.
What that doesn’t cover: these are properties of one well-built MCP server, not a statement about MCP tunneling’s security in general. 2026 has produced a fair amount of hard data on where MCP deployments actually stand, and it’s less reassuring than “the industry has solved this.” A credential audit of over 5,200 public MCP servers found that while 88% require some form of credential, only about 8.5% use OAuth — most rely on static API keys or personal access tokens, often passed via environment variables. Cisco’s 2026 State of AI Security survey found only 29% of organizations feel prepared to secure agentic AI deployments. Separate research into thousands of live MCP server implementations found double-digit percentages carrying path-traversal, code-injection, or command-injection exposure, largely tied to how the STDIO transport handles inbound parameters.
Tunneling specifically introduces its own wrinkle beyond generic MCP risk: the Cloud Security Alliance’s 2026 agentic-MCP guidance flags subdomain hijacking as a live concern for MCP servers exposed through tunnel services — if a tunnel session ends and its subdomain becomes available for reassignment, an attacker who claims it can intercept requests from any client still holding the old URL cached. That’s a reason to treat tunnel URLs as ephemeral in practice, not just in theory, and it’s a point in favor of Pinggy’s design choice to kill tunnels outright on process restart rather than trying to keep a stable subdomain alive unattended.
Net: process-scoped tunnels and OAuth are genuine improvements over pasting a long-lived API token into an agent’s environment, but they address one slice of the exposure — they don’t touch tool-poisoning, confused-deputy patterns where an over-privileged MCP server acts without checking the requesting user’s actual permissions, or the fact that most of the ecosystem still hasn’t adopted OAuth at all. Approving a start_tunnel call is a reasonable control; it’s not a substitute for treating any MCP server with filesystem or network access as something that needs the same scrutiny as production infrastructure.
Current limitations
- Experimental, by the maintainer’s own label. Expect rough edges, tool names or behavior to shift, and file issues rather than assuming stability.
- No persistence across restarts. Since tunnels are tied to the MCP server process, there’s no “resume my tunnel from earlier” — you re-issue the request each session.
- Undocumented parameter schema. The public docs list tool names and purposes but not a full parameter reference, so exact call shapes (what
start_tunnelaccepts beyond port and protocol) aren’t something to rely on precisely without checking the source.
Where this is headed
Vendor MCP servers for developer infrastructure — tunneling, deployment, database access — are still early enough that “experimental” is the accurate word most of them use for themselves, Pinggy included. The plausible near-term direction is more of the same pattern already visible here: an agent calling a tool instead of shelling out, with a public URL or resource handed back into its context automatically. Where this goes for genuinely autonomous multi-agent handoffs — one agent’s tunnel being consumed directly by another agent’s tooling, without either developer manually passing a URL — is a reasonable extrapolation from what already exists, but it isn’t something documented or shipping today, and is worth treating as speculation rather than roadmap.
Changelog
Corrections and additions made to the original draft, verified against Pinggy’s live documentation (pinggy.io/docs/ai_agents/) and the pinggy_mcp GitHub repo:
- Repo path corrected: draft used
github.com/abhimp/pinggy_mcp; the canonical, currently-documented path isgithub.com/Pinggy-io/pinggy_mcp. Noted that the repo’s own README still contains leftover references to the old path internally. - Claude Code install corrected: draft only showed manual JSON config editing; the actual recommended method is the one-line
claude mcp addCLI command. - Claude Desktop Windows/Linux paths added: draft only implied a macOS-style path; added the correct Windows (
%APPDATA%\Claude\...) and Linux (~/.config/Claude/...) paths. - Cursor config path corrected: draft incorrectly gave Cursor the VS Code path (
~/.vscode/mcp.json). Cursor actually uses~/.cursor/mcp.json(global) or.cursor/mcp.json(project). - VS Code separated out as its own client with its correct paths and its different JSON schema (
servers+"type": "stdio", vs.mcpServersfor the other clients) — the draft had merged VS Code and Cursor into one incorrect instruction block. - Windsurf config added: wasn’t covered in the draft at all.
- Tool list replaced with the actual 13 documented tools (auth, tunnels, file sharing, token management), replacing the draft’s invented/approximate tool-call examples.
- Skill vs. MCP server distinction added: the draft conflated “the Pinggy AI skill” with the MCP server; these are two separately installable pieces of tooling with different mechanics.
- “Experimental” status flagged: the draft presented the MCP server as a finished, production-ready feature; Pinggy’s own README labels it explicitly experimental with expected rough edges.
- OAuth 2.0 Device Authorization Grant claim verified accurate — confirmed against the repo’s authentication documentation (RFC 8628).
- WebDAV directory sharing claim verified accurate.
- Security section substantially rewritten: the draft’s “the industry has implemented several guardrails… remains secure” framing was replaced with current 2026 data on MCP security posture (OAuth adoption rate, preparedness surveys, tunnel subdomain hijacking risk) to give an accurate, non-reassuring picture alongside what Pinggy’s specific design does mitigate.
- Added comparison section on how ngrok’s and Cloudflare’s agent-tunneling approaches differ from Pinggy’s, since this wasn’t in the original draft and is relevant context for readers evaluating tools.
- Softened unverifiable specifics: removed literal invented tool-call syntax and specific multi-step automation claims presented as confirmed vendor behavior; reframed as illustrative examples.
- Trimmed promotional framing (“breakthrough,” “magic,” “unprecedented productivity,” “paradigm shift”) in line with house style.
- Speculative “Future” section reduced and explicitly hedged — removed an unverified claim that “swarm MCP servers already exist for UX testing,” since this couldn’t be substantiated.
Related InstaTunnel pages
Continue from this article into the most relevant product guides and workflows.
Comments
Post a Comment