Skip to content
Fizzlayer.
  • Gateway
  • Docs
  • Sensors docs
  • Pricing
  • Hosted list

Gateway docs

Fizzlayer Gateway

One MCP listener in front of your servers, with per-tool rules and pins. These pages match the code in this repository. The hosted URL is available once the shared fleet is deployed and GATEWAY_HOSTED is turned on. It is not on yet. Signed-in setup is at /app. The same routes are in openapi.json.

On this page

  1. Overview
  2. Concepts
  3. Quickstart
  4. Clients
  5. Policies and approvals
  6. Tool pinning
  7. Client tokens and JWKS
  8. Control-plane API
  9. Limits
  10. Troubleshooting
  11. Security

Overview

The data plane is unmodified agentgateway v1.7, pinned by image digest. Fizzlayer does not rebuild that image. The pieces in gateway/ are:

  • fizz-config reads servers from Postgres and writes agentgateway YAML. The write is atomic so the proxy's file watch can reload it. This is standalone mode.
  • fizz-agent is linked mode. It polls the control plane with a registration token and writes that same file. It does not print the token or the YAML.
  • fizz-guard is the ExtMcp service. tools/call is allow, deny, or approve. tools/list pins each tool. Phone approvals reserve a call on the shared monthly cap. /api/cron dials it.
  • The Rust API exposes /api/gateway/* for signed-in users and for a registration token. It does not change /api/mcp, /install.sh, Home Assistant, or /.well-known/*.

Sensors stay at /sensors/docs. That MCP server uses fizz_agent_ tokens. Gateway clients use a JWT. They are different credentials.

public/openapi.json lists the sensors API and the /api/gateway routes. This page is the longer explanation of those routes.

Concepts

Gateway
One agentgateway listener for a workspace. mode is shared, dedicated, or selfhost. Creating the row does not start a process. Self-host requires public_url.
Server
An upstream MCP target. http and sse take a URL without credentials in the URL. stdio takes a command and args, and only on a dedicated or self-hosted gateway whose plan includes stdio.
Policy
A row the guard reads on each call: optional server, tool name or *, effect allow, deny, or approve, and notify_channel log, webhook, or phone. A missing rule denies the call.
Pin
SHA-256 of the canonical JSON {"description","inputSchema","name"}. Status is unreviewed, approved, or changed.
Client token
An ES256 JWT for one person and one gateway. Revocation is a timestamp the guard reads. It is not a reload of the YAML.
Registration token
fizz_reg_…, shown once when the gateway is created or rotated. fizz-agent uses it for GET /api/gateway/agent/config and POST /api/gateway/agent/status. The config response can include upstream keys.

Quickstart

Hosted

Available once deployed. Creating a shared gateway stores https://gw.fizzlayer.com/w/<gateway-id>/mcp. One process serves every active shared gateway at that path. A client token's audience is that URL, so a token for one gateway is rejected on another. HTTP and SSE only. stdio stays on a Pro dedicated gateway, which this fleet does not run. Nothing in this repository points DNS at that host or starts the process.

The app checks GET /api/gateway/hosted, then /gateway-hosted.json. Both stay {"available": false} until you set GATEWAY_HOSTED to 1 on the API after the Compute service is up. This site does not turn that on. Until then, /app shows how to run the gateway yourself. Upstream API keys are decrypted only while the API renders the fleet YAML. The signed-in preview omits them. Tool calls are counted per gateway. Audit rows are kept 7 days on Hobbyist, 30 on Tinkerer, and 90 on Pro once the purge migration is applied. Sensors stay at /sensors.

Self-hosted, standalone

Docker is the only dependency besides the repository. Compose builds the local image. Docker Hub does not have a fizzlayer/fizzlayer-gateway tag yet, so do not docker pull it. The publish workflow on main is what will push that name.

git clone --depth 1 https://github.com/fizzlayer/fizzlayer.git
cd fizzlayer
gateway/compose/test.sh

The script writes gateway/compose/.env with a database password and an admin token, and does not print them. It applies the gateway migrations it mounts, runs the RLS test, and then an MCP client calls through the proxy. ping is allowed. admin_reset is denied and does not reach the sample server. note disappears from tools/list after its description changes. move_funds is rejected, approved once, and rejected on the second retry.

To leave that stack up after a successful run (the test script removes containers when it exits):

cd gateway/compose
docker compose --env-file .env up -d postgres fizz-config fizz-config-watch fizz-guard sample-mcp agentgateway

The proxy listens on 127.0.0.1:3000. Tokens for this compose file use audience http://agentgateway:3000/mcp, which is the name inside the compose network. The approval page is http://127.0.0.1:9002/. Paste FIZZ_GUARD_ADMIN_TOKEN from .env. That page does not place a phone call. Do not publish port 9002.

DATABASE_URL=memory:// keeps pins and approvals in the process and drops them on exit. The compose file uses Postgres. SQLite is not wired.

Linked mode

Linked mode means a gateway you run pulls config from the Fizzlayer API. fizz-agent polls GET /api/gateway/agent/config with a registration token and writes the file agentgateway is watching. Do not run it on the same config.yaml as fizz-config watch. The two writers would overwrite each other. Variable details also live in gateway/README.md.

Create or rotate a gateway to get fizz_reg_…, shown once. The agent does not print the token or the YAML.

fizz-agent environment
VariablePurpose
FIZZ_API_URLOrigin only, such as https://fizzlayer.com. No path, user, or password.
FIZZ_REGISTRATION_TOKEN_FILEFile containing the token. Preferred. Mode 0600.
FIZZ_REGISTRATION_TOKENThe token itself, if you are not using the file.
FIZZ_CONFIG_OUTFile agentgateway was started with (-f). Default /config/config.yaml.
FIZZ_POLL_SECSDelay between pulls. Default 5. Range 1 to 300.
FIZZ_ADMIN_URLOptional origin of the proxy admin listener, such as http://127.0.0.1:15000.
FIZZ_AGENT_STATEOptional file for the last ETag. Default is .fizz-agent-state beside the config.
export FIZZ_API_URL=https://fizzlayer.com
export FIZZ_REGISTRATION_TOKEN_FILE=/run/secrets/fizz-registration
fizz-agent pull

The agent sends Authorization: Bearer, If-None-Match, and ?rev=. 304 leaves the file alone. A 200 is checked before the atomic rename: it has to be YAML with an mcp listener and one target kind per server. A document that fails that check is not written. The last good file keeps being served, and the agent POSTs /api/gateway/agent/status with rejected and a short reason. That reason does not include the token or the YAML. Network errors, 401, and 5xx also leave the file in place and back off up to 60 seconds. A bad document does not use that backoff, so a corrected revision is picked up on the next poll.

agentgateway v1.7.0 watches that file and hot-reloads targets and policies. A reload it rejects stays on the previous in-memory config. GET /api/runtime on the admin listener reports configReload.synchronized: false. There is no separate reload RPC. When FIZZ_ADMIN_URL answers, fizz-agent reads that flag and, if the reload was rejected, puts the previous file back so a restart does not boot the bad document. The rendered config binds admin to 127.0.0.1:15000 inside the proxy container and does not publish it. Leave FIZZ_ADMIN_URL unset unless that listener is reachable from the agent without exposing it on the host.

The signed-in preview at GET /api/gateway/gateways/{id}/config omits credentials, and its ETag ends in -redacted. Upstream API keys are embedded only in the registration-token YAML, as backendAuth.key.value, because agentgateway needs them in config.yaml. Do not log that file.

fizz-guard does not take policies from fizz-agent. The YAML only points mcpGuardrails at the guard. Allow, deny, approve, tool pins, approval rows, and client-token revocation are read from Postgres on each call. A policy change is visible on the next tools/call without a config reload, as long as fizz-guard uses the same database the control plane writes. Linked mode does not sync those rows over the registration token. Point DATABASE_URL at that database, or keep a local database and edit policies there. DATABASE_URL=memory:// does not follow the cloud rows.

20261118000100_gateway_agent.sql stores the agent's last report on gateway.gateways (agent_status, agent_revision, agent_detail). Apply it with the other gateway migrations (supabase db push). Until then the status POST fails and the agent still keeps the last good file. Pulling config itself is 20261114000400. Phone approvals are 20261118000000, which the local compose loads. Local compose does not apply 004 or 00100.

The linked compose test uses a mock control plane on the Docker network. It does not print the token.

gateway/compose/test-linked.sh

That stack adds a server through the mock, checks the new tool shows up without restarting agentgateway, then serves a bad document and checks the previous ping call still succeeds.

Clients

The gateway expects Streamable HTTP and Authorization: Bearer with a Fizzlayer JWT. Mint one with POST /api/gateway/gateways/{id}/tokens after you are signed in. Replace YOUR_GATEWAY_URL with the URL you actually dial, and use a token whose aud is the gateway's configured public URL. Those two strings can differ: the local compose publishes 127.0.0.1:3000 and sets aud to http://agentgateway:3000/mcp.

Claude Code

claude mcp add --transport http fizzlayer YOUR_GATEWAY_URL \
  --header "Authorization: Bearer YOUR_JWT"

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "fizzlayer": {
      "url": "YOUR_GATEWAY_URL",
      "headers": { "Authorization": "Bearer YOUR_JWT" }
    }
  }
}

Generic MCP client

curl YOUR_GATEWAY_URL \
  -H 'Authorization: Bearer YOUR_JWT' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Claude Desktop

If your build of Claude Desktop lets you add a remote MCP server with a custom header, use the same URL and bearer token as Cursor. There is no OAuth login. The connector directory needs an OAuth 2.1 authorization server, which is not built, so a directory install will not work yet.

ChatGPT

Not supported. Custom connectors and directory apps need OAuth 2.1 with PKCE. Fizzlayer does not publish that authorization server. A bearer JWT is not a substitute ChatGPT will use as the user login.

There is no fizzlayer connect command. Copy the JSON yourself.

Policies and approvals

Put a rule with PUT /api/gateway/gateways/{id}/policies:

curl https://fizzlayer.com/api/gateway/gateways/GATEWAY_ID/policies \
  -H 'Authorization: Bearer SUPABASE_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"tool_name":"*","effect":"approve","notify_channel":"log"}'

tool_name is * or a name matching ^[A-Za-z0-9_.:-]{1,128}$. server_id is optional. Omit notify_channel on an update to keep the current value. A new row defaults to log. Uniqueness is the gateway, the server (or every server), and the tool name.

When the effect is approve, fizz-guard stores sha256 of the canonical arguments, rejects, and returns. It does not wait inside the guardrail timeout. Default TTL is 10 minutes (FIZZ_APPROVAL_TTL_SECS).

Approval notification channels
notify_channelWhat happens
logOne line: channel, tool, server, short id, result. No argument values.
webhookPOST that summary to FIZZ_APPROVAL_WEBHOOK_URL with a 2 second timeout. A URL with a username or password is ignored. If the POST fails, the approval row still exists.
phoneReserves one call against the shared monthly cap and returns. It does not dial inside the guard. /api/cron dials with the same AgentPhone path as sensor alerts. The greeting names the gateway, tool, argument summary, and id, and tells you to approve in the app. Digit collection is not available from the provider. A full cap, a missing paired number, or unreadable billing is skipped and does not count. The guard then falls back to the webhook or a log line.

Decide a pending row that has not expired:

curl -X POST https://fizzlayer.com/api/gateway/gateways/GATEWAY_ID/approvals/APPROVAL_ID/decision \
  -H 'Authorization: Bearer SUPABASE_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"status":"approved"}'

status is approved or denied. args_preview on the list endpoint is key names only. Owner and admin can write. A member can read and gets 403 on writes. Another workspace gets 404.

Tool pinning

gateway.gateways.unreviewed_tools is hide (the default) or show. A tool the guard has not seen is stored as unreviewed. hide removes it from tools/list. show leaves it listed. Either way, tools/call is denied until the pin is approved.

If a later list has a different hash, the tool is removed from that response, status becomes changed, and gateway.pin_alerts gets one open row. description_preview is untrusted text from the MCP server, cut to 200 characters.

curl -X POST https://fizzlayer.com/api/gateway/gateways/GATEWAY_ID/pins/approve \
  -H 'Authorization: Bearer SUPABASE_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"server":"sample","tool":"note"}'

That copies observed_sha256 onto pin_sha256, sets status approved, and acknowledges open pin alerts for that tool. PATCH the gateway with {"unreviewed_tools":"hide"} or "show" to change the default.

Client tokens and JWKS

GET /api/gateway/jwks is public. No session. Agentgateway checks tokens with jwtAuth: issuer fizzlayer, mode strict, audience equal to the gateway public URL, JWKS from GATEWAY_JWKS_URL or the request origin plus /api/gateway/jwks.

Claims: iss, sub (the Fizzlayer user id), aud, ws (workspace id), jti, iat, exp. Algorithm ES256. The private key is GATEWAY_SIGNING_KEY, a PKCS#8 PEM. The server does not generate one. A single-line value may use \n for line breaks.

curl -X POST https://fizzlayer.com/api/gateway/gateways/GATEWAY_ID/tokens \
  -H 'Authorization: Bearer SUPABASE_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Cursor on laptop","ttl_seconds":3600}'

The JWT is returned once. Default life is 1 hour. ttl_seconds must be from 60 to 2592000 (30 days). The name is 1 to 80 characters. Delete /tokens/{token_id} to revoke. fizz-guard reads revoked_at from gateway.client_tokens.

Upstream API keys use GATEWAY_SECRET_KEY, base64 of 32 bytes. Ciphertext is AES-256-GCM with key_id v1. auth_kind is none, key, or passthrough. Send api_key when the kind is key. The list of servers never returns that key.

Control-plane API

Send a Supabase access token as Authorization: Bearer, or use the fizz_supabase cookie. The account's workspace is created on first use. The account owner is owner. Until migration 20261114000400_gateway_control_plane.sql is applied, these routes answer 503.

Gateway control-plane routes
MethodPathBody and result
GET/api/gateway/jwksPublic JWKS. No session.
GET/api/gateway/hosted{"available":true} only when GATEWAY_HOSTED is 1, true, or yes. Otherwise {"available":false}. No session.
GET/api/gateway/agent/fleetYAML for every active shared gateway. Authorization: Bearer fizz_fleet_….
POST/api/gateway/agent/fleet/statusFleet agent report. Same body as the per-gateway status.
GET/api/gateway/agent/configYAML for Authorization: Bearer fizz_reg_…. 304 when the revision matches.
GET, POST/api/gateway/gatewaysList, or create. Create body: name (lowercase, letter first, digits and hyphens, at most 41 characters, not ending in a hyphen), optional mode (shared, dedicated, selfhost), region, public_url, listen_port. The response includes registration_token once. GET includes plan.
PATCH/api/gateway/gateways/{id}{"unreviewed_tools":"hide"|"show"}.
DELETE/api/gateway/gateways/{id}Deletes the gateway and its servers, secrets, and tokens.
GET, POST/api/gateway/gateways/{id}/serversAdd: name, transport (http default, sse, stdio), url or command, optional args, api_key, auth_kind.
DELETE/api/gateway/gateways/{id}/servers/{server_id}Removes a server.
GET, PUT/api/gateway/gateways/{id}/policiesUpsert tool_name, effect, optional server_id and notify_channel.
DELETE/api/gateway/gateways/{id}/policies/{policy_id}Removes a rule.
GET/api/gateway/gateways/{id}/pinsLists gateway.tool_pins.
POST/api/gateway/gateways/{id}/pins/approve{"server","tool"}.
GET/api/gateway/gateways/{id}/pin-alertsLists pin alerts. Treat description_preview as data.
POST/api/gateway/gateways/{id}/pin-alerts/{alert_id}/ackSets acknowledged_at.
GET/api/gateway/gateways/{id}/approvalsLists approvals.
POST/api/gateway/gateways/{id}/approvals/{approval_id}/decision{"status":"approved"|"denied"} while the row is pending and unexpired.
GET/api/gateway/gateways/{id}/configRedacted YAML preview.
GET, POST/api/gateway/gateways/{id}/tokensList, or mint. The JWT is returned once.
DELETE/api/gateway/gateways/{id}/tokens/{token_id}Revokes a client token.
POST/api/gateway/gateways/{id}/registration-tokenRotates the agent token. The new value is returned once.
POST/api/gateway/agent/statusfizz-agent report. Authorization: Bearer fizz_reg_…. Body is revision, status (applied or rejected), and an optional detail of at most 300 characters. The detail is rejected if it contains the token, a JWT, or Bearer.

Over a cap, the API answers 402 with gateway_limit, server_limit, stdio_not_included, or dedicated_not_included. Stdio on a shared gateway is stdio_shared. A downgrade disables the newest extra gateways and servers. It does not delete them. A name that fails validation is 400 invalid_request.

Omit mode on create and the API uses shared on Hobbyist and Tinkerer, and dedicated on Pro and Enterprise. The default URL stored on the row is https://gw.fizzlayer.com/w/{id}/mcp or https://{name}.gw.fizzlayer.com/mcp. The shared host answers only after the fleet is deployed. The dedicated host is not provisioned.

Environment on the API, not committed:

  • GATEWAY_SIGNING_KEY to mint tokens and serve JWKS.
  • GATEWAY_SECRET_KEY to store an MCP API key.
  • GATEWAY_JWKS_URL absolute URL written into YAML as jwtAuth.jwks.url.
  • GATEWAY_GUARD_HOST optional, default fizz-guard:9001. On the single hosted container set 127.0.0.1:9001.
  • GATEWAY_FLEET_TOKEN for the shared fleet pull. Same value as FIZZ_FLEET_TOKEN on the Compute service.
  • GATEWAY_HOSTED optional. Set to 1 after deploy. Unset keeps GET /api/gateway/hosted at {"available":false}.

Rendered YAML sets adminAddr to 127.0.0.1:15000, session key disabled, statefulMode: stateless, prefixMode: never, and mcpGuardrails with failureMode: failClosed on tools/call request and tools/list response.

Limits

Numbers are the columns on fizz_plans from 20261114000400_gateway_control_plane.sql. Phone calls are shared with sensor alert calls and reset on the first of each month (UTC). Enterprise phone calls are unlimited unless fizz_subscriptions.monthly_call_cap is set.

Plan limits for the gateway
PlanPriceGatewaysServersTool calls / monthPhone callsAudit daysSeatsstdio / dedicated
Hobbyist$01310,000071No
Tinkerer$10 / month11050,00020301No
Pro$25 / month125200,000100903Yes, not provisioned
EnterpriseCustomCustomCustomCustomCustomCustomCustomYes, not provisioned

Enforced when you call the API: gateway count, server count, the dedicated flag, the stdio flag, and the phone-call cap. On the shared fleet, fizz-guard also rejects a tool call past the monthly tool-call number and records decision quota. /api/cron deletes audit rows older than the plan's audit days after 20261118000200_hosted_gateway.sql is applied. usage_daily is kept for later metering. Seat count is not a login limit. Stripe does not receive gateway usage records yet. Sensor device and credit limits are unchanged: Hobbyist 3 devices and 10 credits, Tinkerer 10 and 100, Pro 50 and 1,000. Email and webhook alerts are on every plan, including Hobbyist. The dashboard hides email until mail is configured.

Troubleshooting

503 from /api/gateway
The control-plane migration is not applied, or the handler cannot reach the database. supabase db push applies 20261114000400_gateway_control_plane.sql. Signing also needs GATEWAY_SIGNING_KEY before minting a token.
401
The session token was missing or rejected, or a registration token was rejected on the agent route. Sign in again, or rotate the registration token. The old registration token stops working.
402
gateway_limit, server_limit, stdio_not_included, or dedicated_not_included. Disable a gateway or server, or use a plan that includes that mode. A downgrade disables extras. It does not delete them.
The tool is missing from tools/list
It is unreviewed and unreviewed_tools is hide, or the description or schema changed. Approve the pin. Read description_preview as untrusted text.
tools/call says approval is required
Approve that id, then retry the same arguments before the TTL. A different argument hash is a new approval. A second identical retry after a success is rejected.
Every call is denied and the guard is healthy
There is no matching allow or approved pin. The default is deny. failureMode is failClosed, so a guard error also denies.
The client connects and the JWT is rejected
The aud claim must match the audience in the generated YAML, which is the gateway public URL. For the local compose file that is http://agentgateway:3000/mcp, even if you dial 127.0.0.1:3000.
Phone approval did not ring
Hobbyist cannot place calls. The cap may be spent. The number must already be paired. AGENTPHONE_API_KEY and AGENTPHONE_AGENT_ID must be set. The guard only reserves the call. /api/cron dials it. A skipped reservation does not decrement the cap.
Config pull returns YAML the proxy will not load
On standalone, fizz-config refuses to write a credential and refuses stdio on a shared gateway. Check the container logs. They are scrubbed for tokens in gateway/compose/test.sh when the test fails.

Security

  • The guard fails closed. A crashed sidecar is a deny, not an allow.
  • Shared gateways cannot run stdio. A dedicated or self-hosted gateway can. The process is not given a seccomp or container sandbox by this repo. Treat stdio as a command you are willing to run.
  • Do not publish the admin UI. It binds to localhost. An empty upstream config can serve /ui/ without auth. The rendered file sets adminAddr to 127.0.0.1:15000.
  • Do not publish port 9002. The admin token can decide every pending row in that database.
  • The registration-token YAML can contain upstream API keys. The signed-in preview does not. Neither response should be logged.
  • Client JWTs are bearer secrets. Prefer a short TTL. Revocation depends on fizz-guard reading revoked_at, not on the YAML file changing.
  • Webhook URLs with embedded passwords are ignored. Pin alert text is attacker-controlled if the MCP server is.
  • This product does not claim to prevent prompt injection. A tool result can still instruct the model. The gateway decides whether the next tool call is allowed.
  • License: Apache-2.0, copyright 2026 Fizzlayer LLC. agentgateway is included under its own Apache-2.0 license. See gateway/NOTICE.

Repository notes: gateway/README.md. Sensor setup: /sensors/docs.

Fizzlayer.The secure connection layer for AI agents.
GatewayGateway docsSensors docsSelf-hostPricingFor AI agents