Gateway CLI and HTTP API

Flags#

Flag	What it does
`--http [port]`	Serve over HTTP instead of stdio. Default port `8765`.
`--insecure-loopback`	Allow unauthenticated HTTP on a loopback bind. Local development only; never permits an open non-loopback bind.
`--selftest-secrets`	Diagnostic: read every vaulted secret and report.
`-h`, `--help`	Print usage and exit.
`-V`, `--version`	Print the version and exit.

--http-proxy, --daemon, --stdio-adapter, --toolport-hook and --toolport-guard are internal: the desktop app and the hooks it installs use them.

Use --http in scripts, services and containers. TOOLPORT_HTTP is ignored when stdin is a pipe, so a machine-wide env var cannot turn every client-spawned gateway into an HTTP server fighting over the port.

Start it#

export TOOLPORT_HTTP_TOKEN="$(openssl rand -hex 24)"
toolport-gateway --http 8765

HTTP endpoints#

Endpoint	Use
`GET /openapi.json` + `POST /{tool}`	Open WebUI, n8n, LibreChat (OpenAPI)
`POST /mcp`	MCP clients over streamable HTTP
`GET /mcp`	Legacy MCP session listen stream
`GET /`	Short help text
`GET /metrics`	Prometheus metrics, with `TOOLPORT_METRICS=1`

Auth is a bearer token (TOOLPORT_HTTP_TOKEN or a registered httpClients[] entry).

Call it with curl#

Modern MCP 2026-07-28 requests are sessionless: no initialize, no session header.

curl -s -X POST http://127.0.0.1:8765/mcp \
  -H "Authorization: Bearer $TOOLPORT_HTTP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1"},"io.modelcontextprotocol/clientCapabilities":{}}}}'

Legacy clients still initialize, receive Mcp-Session-Id, and reuse it on later requests. POST /mcp returns JSON by default, or a single SSE message event when Accept prefers text/event-stream.

Metrics#

curl -s -H "Authorization: Bearer $TOOLPORT_HTTP_TOKEN" \
  http://127.0.0.1:8765/metrics

Counters cover tool calls (server, tool, client, ok), held destructive calls, duration, exact catalog bytes avoided, estimated token equivalent, tool-list loads and discovery response bytes. Labels are ids only, never arguments.

Updated Sep 25, 2026