Skip to main content
Use Gemini CLI with Plainrouter over Streamable HTTP. This guide is for the terminal client, not the Gemini web app. Install and sign in to Gemini CLI first. You need a Plainrouter account and access to the intended workspace. The unauthenticated sandbox is retired; start with a Read key and verify the workspace result.

1. Create a workspace key

In Plainrouter, select your workspace and open Settings → Workspace keys. Create a Read key for analysis; use Write for Actions previews and proposals. A new Read key can also inspect Actions records and policy. Copy it once into your protected credential configuration. Select the intended workspace under Workspaces. A key can cover a fixed set of workspaces; for more than one, call list_workspaces and pass workspace_id on later tool calls. Workspace selection. Never put keys in prompts or source control. Key permissions and replacement.

2. Add Plainrouter to the client

Merge this entry into ~/.gemini/settings.json, preserving other settings:
Provide PLAINROUTER_WORKSPACE_KEY through your local secret manager in the environment that starts Gemini CLI. Leave the variable reference in the file. Restart the client, check /mcp, and select plainrouter for production reads.

3. Verify the connection

Start with this read-only request:
Check the tool result, not just the assistant’s summary: the workspace must be yours and the call must succeed. This workspace-only read works before connecting Meta. For account diagnostics, connect Meta and verify the selected account. Agent replies can vary. In Ask, changes wait for approval. Auto can run enabled agent action types without individual approval; Full can run admitted agent actions without individual approval. Policy blocks remain effective in every mode. A client’s tool confirmation is separate from Plainrouter’s execution controls.

4. Troubleshooting

  • Disconnected: use httpUrl or --transport http; url configures the older SSE transport.
  • Tools appear but calls return 401: discovery can be public. Confirm the key variable is available to the client and has not expired or been revoked.
  • Wrong server is used: remove a retired plainrouter-test entry and select the authenticated plainrouter connection in your request.
References: Gemini CLI MCP configuration and settings variable expansion. Choose another client.