TinyFish MCP Server

What is TinyFish MCP Server about?

TinyFish MCP Server acts as a transparent reverse proxy exposing a local Streamable‑HTTP MCP endpoint at http://127.0.0.1:3711/mcp. Every request is forwarded to the hosted TinyFish MCP service while preserving headers, streaming SSE data, and JSON payloads.

How to use TinyFish MCP Server?

1. Ensure Node.js >= 22 is installed.
2. Set the required environment variable:

   export TINYFISH_API_KEY=tf_YourKeyHere
   

3. Start the server with the easiest command:

   npx @tiny-fish/mcp
   

   The process binds to 127.0.0.1:3711 and prints a one‑line status message.
4. Point any MCP‑compatible client (Claude Code, Claude Desktop, Cursor, VS Code, etc.) to the local URL http://127.0.0.1:3711/mcp.
5. Optional configuration via environment variables:
   • PORT – custom listen port (default 3711).
   • TINYFISH_UPSTREAM_URL – alternate upstream MCP URL.

Key Features

• Loopback‑only server – binds exclusively to 127.0.0.1, preventing external access.
• Origin validation – rejects requests with non‑local Origin headers (mitigates DNS‑rebinding attacks).
• API‑key handling – reads TINYFISH_API_KEY once at startup and forwards it as X‑API‑Key.
• Transparent relaying – streaming SSE and JSON responses are passed verbatim; non‑streaming JSON is re‑serialized without alteration.
• Attribution headers – automatically adds X‑TF‑Request‑Origin, X‑TF‑Client‑Name, and X‑TF‑Client‑Version.
• Simple health check – GET /healthz returns 200 OK for debugging.
• Configurable port and upstream URL via environment variables.

Use Cases

• Local development where the client only supports a local MCP server.
• CI/CD pipelines or headless scripts that need to authenticate with a TinyFish API key instead of the hosted OAuth flow.
• Debugging / monitoring of MCP traffic by inspecting the proxied requests and responses locally.
• Enabling web‑automation tools (Claude Code, Claude Desktop, Cursor, VS Code) to interact with TinyFish agents through a consistent local endpoint.

FAQ

• Port 3711 already in use? Set a different port with PORT=xxxx before starting the server and update client configurations.
• Do I need to install the package globally? No, you can run it directly with npx @tiny-fish/mcp.
• Can the server bind to a non‑loopback interface? No, the bind address is fixed to 127.0.0.1 for security.
• How do I verify the server is running? Request GET http://127.0.0.1:3711/healthz; a 200 OK response confirms it.
• What does HTTP 502 -32001 mean? The upstream rejected the request; double‑check that TINYFISH_API_KEY is valid and correctly set in the server’s environment.
• What does HTTP 502 -32000 indicate? The upstream server is unreachable; check network connectivity, VPN/proxy settings, or the TINYFISH_UPSTREAM_URL value.
• Can I send batch JSON‑RPC requests? MCP does not support batching; send one request per call.

@tiny-fish/mcp

TinyFish local MCP server — a transparent reverse proxy that exposes a local Streamable-HTTP MCP endpoint at http://127.0.0.1:3711/mcp and forwards every request to the hosted TinyFish MCP server at https://agent.tinyfish.ai/mcp.

The proxy defines no tools and no schemas of its own. tools/list, tools/call, resources/*, errors, and the run_web_automation SSE progress stream all come from the hosted server: streaming (SSE) responses are relayed byte-verbatim, and non-streaming JSON responses are relayed content-identical (parsed and re-serialized, deep-equal to upstream). What the hosted server says is what your client sees.

Use the hosted server first

If your MCP client supports remote Streamable-HTTP servers (Claude Code, Claude Desktop connectors, Cursor, VS Code, and most modern clients do), connect it directly to the hosted server — no install, no local process:

https://agent.tinyfish.ai/mcp

Use this package instead when:

• your client only talks to local MCP servers, or
• you want to authenticate with a TinyFish API key from your environment instead of the hosted server's OAuth flow (CI, headless machines, scripts).

Install

npm install -g @tiny-fish/mcp

Or run it without installing:

npx @tiny-fish/mcp

Requires Node.js >= 22. (This is a deliberate deviation from the TinyFish CLI's >=24 requirement — nothing here needs Node 24.)

API key

The server reads TINYFISH_API_KEY from its environment at startup and sends it upstream as X-API-Key on every call. Get a key at https://agent.tinyfish.ai.

export TINYFISH_API_KEY=tf_...
tinyfish-mcp

On success it prints one line to stderr:

tinyfish-mcp [info] listening on http://127.0.0.1:3711 — upstream https://agent.tinyfish.ai/mcp — v0.1.0

The key is never logged and never echoed back to clients.

Client configuration

Start tinyfish-mcp (e.g. in a terminal, or under your process manager of choice), then point your client at http://127.0.0.1:3711/mcp.

Claude Code

claude mcp add --transport http tinyfish http://127.0.0.1:3711/mcp

Claude Desktop

Settings → Connectors → Add custom connector, with URL http://127.0.0.1:3711/mcp. On versions whose claude_desktop_config.json supports URL-based servers:

{
  "mcpServers": {
    "tinyfish": {
      "url": "http://127.0.0.1:3711/mcp"
    }
  }
}

Note: Claude Desktop can also use the hosted https://agent.tinyfish.ai/mcp directly as a custom connector — prefer that unless you need API-key auth.

Cursor

~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "tinyfish": {
      "url": "http://127.0.0.1:3711/mcp"
    }
  }
}

VS Code

.vscode/mcp.json:

{
  "servers": {
    "tinyfish": {
      "type": "http",
      "url": "http://127.0.0.1:3711/mcp"
    }
  }
}

Any other client

Configure a Streamable-HTTP (remote/URL) MCP server with:

{ "url": "http://127.0.0.1:3711/mcp" }

The endpoint accepts POST /mcp only (matching the hosted server, which has no GET SSE channel and no DELETE session teardown). GET /healthz returns 200 ok for debugging.

Environment variables

Variable	Default	Description
TINYFISH_API_KEY	(required)	TinyFish API key, sent upstream as X-API-Key. The server refuses to start without it.
PORT	3711	Local listen port (integer 1-65535). No auto-increment: if the port is busy the server exits with an error.
TINYFISH_UPSTREAM_URL	https://agent.tinyfish.ai/mcp	Upstream MCP URL. Must be https:; http: is allowed only for 127.0.0.1/localhost (local testing).

The proxy also sends attribution headers on every upstream call: X-TF-Request-Origin: tinyfish-mcp, X-TF-Client-Name: tinyfish-mcp, and X-TF-Client-Version: <package version>.

Security & trust model

This is a loopback-only server with a deliberate, documented trust boundary:

• Loopback bind, always. The server binds the 127.0.0.1 literal and this is not configurable — it can never listen on 0.0.0.0 or a LAN interface.
• Origin validation. Requests carrying an Origin header are rejected with 403 unless the origin is http(s)://127.0.0.1 or http(s)://localhost (any port). This blocks the DNS-rebinding attack the MCP spec calls out for local HTTP servers. Requests without an Origin header (curl, MCP SDKs, inspectors) are allowed.
• Server-holds-key. The process reads TINYFISH_API_KEY from its env; clients send no credential on the local hop. This is the simplest model, but it means any local process that can reach 127.0.0.1:<port> can use your key and drive automations (which can spend TinyFish credits). The loopback bind and Origin check are the mitigations; treat the port as a local trust boundary on a machine you trust.

Troubleshooting

"Port 3711 is already in use" — another process holds the port. Stop it, or set PORT to a free port and update your client config to match.

HTTP 502 with JSON-RPC error -32001 ("Upstream rejected the request … check that TINYFISH_API_KEY is set to a valid TinyFish API key") — the hosted server rejected your key. Verify TINYFISH_API_KEY is set in the environment of the tinyfish-mcp process (not just your shell) and that the key is valid at https://agent.tinyfish.ai. The error's data carries the upstream status and (truncated) body for diagnosis.

HTTP 502 with JSON-RPC error -32000 ("cannot reach …") — the upstream server is unreachable: check your network/proxy/VPN; the hosted server may also be temporarily down. If you overrode TINYFISH_UPSTREAM_URL, check it. If a streamed run_web_automation call fails mid-stream you get the same -32000 as the final SSE frame, with a "the run may still be executing" warning and the runId when known — check the run's status instead of retrying blindly.

Batch requests don't work — MCP forbids JSON-RPC batching and the hosted server does not support batch arrays. The proxy forwards a batch as-is and the upstream answers its own error; send one JSON-RPC message per request.

Claude/other client can't connect — make sure tinyfish-mcp is actually running (it's a standalone server; clients do not launch it) and that GET http://127.0.0.1:3711/healthz answers ok.

Development

npm ci
npm run build        # tsc → dist/, marks dist/index.js executable
npm test             # unit tests (offline, mock upstream)
npm run test:watch   # unit tests in watch mode
npm run lint         # eslint over src/ tests/
npm run format       # prettier
npm run type-check   # tsc --noEmit over the whole tree

Layout: src/core/ is the transport-agnostic proxy core (upstream client, session bridge, SSE relay, error shaping); src/http/ is the thin HTTP adapter (routing, Origin check); tests/ holds the unit suites plus tests/helpers/mock-upstream.ts, a mock of the hosted endpoint that the unit tests run against entirely offline.

Integration tests hit the real hosted upstream and are gated: without TINYFISH_API_KEY they skip with a printed notice.

TINYFISH_API_KEY=... npm run test:integration

Set TINYFISH_UPSTREAM_URL to point them at a sandbox deployment instead of production. Note the run_web_automation integration test executes a real automation and spends credits.

Maintenance

Maintained by @Zechereh. Bugs and feature requests: GitHub issues.

License

MIT