Hooklistener

MCP setup · Gemini CLI

Hooklistener MCP server for Gemini CLI

Run gemini mcp add --transport http --scope user hooklistener https://app.hooklistener.com/api/mcp, start Gemini CLI and run /mcp auth hooklistener to sign in with your browser. In settings.json the entry must use httpUrl, because a plain url means SSE in Gemini CLI. After that, Gemini can create webhook URLs, wait for events and replay them from the terminal.

Setup checked against Gemini CLI docs, September 2026

Terminal
gemini mcp add --transport http --scope user hooklistener https://app.hooklistener.com/api/mcp

# then, inside Gemini CLI:
/mcp auth hooklistener
Add command
gemini mcp add --transport http
Config file
~/.gemini/settings.json or .gemini/settings.json
Transport field
httpUrl (url = SSE)
Sign-in
/mcp auth hooklistener
Read-only
oauth.scopes: ["read_only"]

Setup

Connect Gemini CLI step by step

  1. 01

    Add the server

    --scope user writes to ~/.gemini/settings.json; --scope project writes to .gemini/settings.json in the current project. The result looks like this:

    ~/.gemini/settings.json
    {
  "mcpServers": {
    "hooklistener": {
      "httpUrl": "https://app.hooklistener.com/api/mcp"
    }
  }
}
  2. 02

    Sign in

    Gemini CLI detects the 401, discovers Hooklistener's OAuth endpoints and registers itself. Run /mcp auth hooklistener to open the browser and Authorize. Tokens are stored in ~/.gemini/mcp-oauth-tokens.json and refreshed automatically; run the same command again if they ever expire.

  3. 03

    Check that it connected

    /mcp inside Gemini CLI lists servers, tools and connection state. From the shell, gemini mcp list shows the same status.

    Terminal
    gemini mcp list

Read-only access

Gemini CLI's oauth object accepts scopes, and clientId is optional when the server supports dynamic registration, which Hooklistener does. Request read_only and the token can inspect but never write. Re-run /mcp auth hooklistener after changing it.

~/.gemini/settings.json
{
  "mcpServers": {
    "hooklistener": {
      "httpUrl": "https://app.hooklistener.com/api/mcp",
      "oauth": {
        "enabled": true,
        "scopes": ["read_only"]
      }
    }
  }
}

Try it

What to ask Gemini CLI

Plain-language requests work; Gemini CLI picks from Hooklistener's 67 tools. These are the ones each prompt usually calls.

Create an MQTT-over-WebSocket endpoint, connect my device simulator to it and show me the first five messages.

Hooklistener hosts the broker endpoint; Gemini reads what your client publishes.

  • create_realtime_endpoint
  • wait_for_realtime_message
  • get_realtime_messages

Set up an SSE endpoint that sends a hello event on connect, and check my dashboard reconnects after I restart it.

The endpoint sends your payload to every new client; sessions show each reconnect.

  • create_realtime_endpoint
  • list_realtime_sessions

Show me the plan, then replay the Slack event my local tunnel captured a minute ago.

Tunnel actions are planned first and need a scoped grant before they run.

  • plan_tunnel_action
  • replay_tunnel_capture

Wait for the next Slack event and verify its signing secret.

Checks Slack's v0 signature against a stored secret.

  • wait_for_request
  • verify_request_signature

Troubleshooting

When Gemini CLI doesn't connect

Configured with "url" and it won't connect
In Gemini CLI, url selects the SSE transport. Hooklistener speaks Streamable HTTP, so the field must be httpUrl. There is no type field to set.
The server fails silently
Gemini CLI hides connection errors by default. Run /mcp list or gemini mcp list to see the diagnostics.
Should you set "trust": true?
trust: true skips every tool confirmation, including replays and deletes. Leave it off for Hooklistener, or pair it with the read_only scope.
Blocking waits stop early
By default the wait tools return a task immediately. With blocking: true they hold the call open for up to 60 seconds, well inside Gemini's default timeout of 600,000 ms. If you lowered timeout, keep it above 60000.

FAQ

Gemini CLI and Hooklistener: common questions

Should I use url or httpUrl for a Streamable HTTP server in Gemini CLI?

httpUrl. Gemini CLI maps url to SSE and httpUrl to Streamable HTTP, and Hooklistener's server is Streamable HTTP.

Does Gemini CLI support OAuth for remote MCP servers?

Yes. It discovers OAuth from the server's 401 response, supports dynamic client registration and stores tokens in ~/.gemini/mcp-oauth-tokens.json. /mcp auth <name> starts or repeats the flow.

Can Gemini CLI have read-only access?

Yes. Add "oauth": {"enabled": true, "scopes": ["read_only"]} to the server entry and sign in again.

Where is the Gemini CLI MCP config?

~/.gemini/settings.json for your user, or .gemini/settings.json in a project, under mcpServers.

Keep going

More on the MCP server

Server URL: https://app.hooklistener.com/api/mcp

Other clients

Set up Hooklistener in another tool

Give Gemini CLI a webhook URL it can watch

The free plan includes the MCP server, 1 debug endpoint, 1 email inbox and 1 uptime monitor. No credit card.

Start freeSee all MCP tools