Hooklistener

MCP setup · OpenCode

Hooklistener MCP server for OpenCode

Add Hooklistener to opencode.json under mcp with "type": "remote" and the server URL, then run opencode mcp auth hooklistener to sign in with your browser. OpenCode also starts the OAuth flow on its own when it sees Hooklistener's 401. From then on OpenCode can create webhook URLs, wait for events and replay them from the terminal.

Setup checked against OpenCode docs, September 2026

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hooklistener": {
      "type": "remote",
      "url": "https://app.hooklistener.com/api/mcp"
    }
  }
}
Config file
opencode.json or ~/.config/opencode/opencode.json
Type
"type": "remote"
Sign-in
opencode mcp auth hooklistener
Tokens
~/.local/share/opencode/mcp-auth.json
Debug
opencode mcp list / opencode mcp debug

Setup

Connect OpenCode step by step

  1. 01

    Add the server

    Put it in opencode.json at the project root, or in ~/.config/opencode/opencode.json for every project. The files are merged, so a project entry adds to your global ones. JSONC (comments) is supported.

    opencode.json
    {
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hooklistener": {
      "type": "remote",
      "url": "https://app.hooklistener.com/api/mcp",
      "enabled": true
    }
  }
}
  2. 02

    Sign in

    OpenCode detects the 401, registers itself with dynamic client registration and opens the browser. To run it explicitly:

    Terminal
    opencode mcp auth hooklistener
  3. 03

    Check that it connected

    opencode mcp list shows every server and its auth status. opencode mcp debug hooklistener helps when it doesn't connect.

    Terminal
    opencode mcp list
opencode mcp debug hooklistener

Read-only access

The grant OpenCode receives is Hooklistener's default full access, shown on the consent page. To narrow what the model can call, use OpenCode's tools setting to switch a server's tools off globally and back on only for the agents that need them.

Try it

What to ask OpenCode

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

Create an endpoint for Clerk user.created, sign up a test user and wait for the webhook.

OpenCode reads the payload and headers back.

  • create_endpoint
  • wait_for_request

Validate every captured user.created against schemas/user.json and fix the handler where they differ.

Schema checks run server-side; OpenCode edits code against the failures.

  • list_requests
  • validate_request

Test our Socket.IO chat client: create an endpoint, connect, and echo back a join event.

Hooklistener speaks Socket.IO, so no throwaway server to write.

  • create_realtime_endpoint
  • wait_for_realtime_message
  • send_realtime_message

Run the saved replay suite against localhost:8080 and show me any assertion that failed.

Status, body subset and schema assertions come back per case.

  • list_endpoint_case_suites
  • run_endpoint_cases
  • get_case_run

Troubleshooting

When OpenCode doesn't connect

Used "type": "http" or "streamable-http"
OpenCode's remote servers use "type": "remote". Other values from Claude Code or VS Code configs won't load.
OAuth never starts
Check you didn't copy "oauth": false from an API-key example; that turns automatic OAuth off. Remove it and run opencode mcp auth hooklistener.
Tools time out on first load
timeout controls how long OpenCode waits to fetch the tool list (5000 ms by default). Raise it on slow networks.
Your context fills up quickly
Every MCP server adds its tool definitions to the context. Hooklistener lists only the toolsets your workspace uses (26 tools for a new one), but you can still set "enabled": false when you aren't testing webhooks, or turn tools off per agent.

FAQ

OpenCode and Hooklistener: common questions

What does a remote MCP server look like in opencode.json?

Under mcp: "hooklistener": {"type": "remote", "url": "https://app.hooklistener.com/api/mcp"}. Add headers only for servers that need a static key.

Does OpenCode support OAuth for MCP servers?

Yes. It detects a 401, uses dynamic client registration when the server supports it, and stores tokens in ~/.local/share/opencode/mcp-auth.json. opencode mcp logout hooklistener removes them.

Where does OpenCode read config from?

Global ~/.config/opencode/opencode.json, then the project's opencode.json, among other sources. They are merged, with later sources overriding earlier keys.

Keep going

More on the MCP server

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

Other clients

Set up Hooklistener in another tool

Give OpenCode 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