Klaxon

Appearance

Connecting an Agent ​

Klaxon exposes a standard MCP server over HTTP. Any MCP-compatible client can connect using bearer token auth.

Get the Connection Details ​

When Klaxon launches, the MCP server starts on an ephemeral port and prints connection details to stderr:

MCP server listening at http://127.0.0.1:39305/mcp
MCP bearer token: mcp_ZRuUOZDgfwjsCv9SCTVcbavITyHK

You can also see them in the Main window → ⚙ Settings → MCP tab, which has copy buttons and ready-made snippets for popular clients. (The tray's "Settings" menu item deep-links straight to that tab.)

Pin a port

By default Klaxon picks a random free port on each launch — but persists the auto-picked port between launches if "Auto-pick port" is enabled, so agents stay registered. To pin a specific port permanently, set Main window → ⚙ Settings → MCP → Port and uncheck "Auto-pick port".

Claude Code ​

Use the claude mcp add command from your terminal:

bash
claude mcp add --transport http klaxon "http://127.0.0.1:<port>/mcp" \
  --header "Authorization: Bearer mcp_<token>"

Verify it registered:

bash
claude mcp list

You can now ask Claude Code to use Klaxon tools — try "send a Klaxon notification saying hello".

Claude Desktop ​

Add Klaxon to your claude_desktop_config.json under mcpServers:

json
{
  "mcpServers": {
    "klaxon": {
      "type": "http",
      "url": "http://127.0.0.1:<port>/mcp",
      "headers": {
        "Authorization": "Bearer mcp_<token>"
      }
    }
  }
}

Config file location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop for the change to take effect.

Generic MCP Client (curl) ​

Test the server with a raw initialize request:

bash
curl -X POST http://127.0.0.1:<port>/mcp \
  -H "Authorization: Bearer mcp_<token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "test", "version": "1.0"}
    }
  }'

The response includes an Mcp-Session-Id header — pass it on subsequent requests:

bash
curl -X POST http://127.0.0.1:<port>/mcp \
  -H "Authorization: Bearer mcp_<token>" \
  -H "Mcp-Session-Id: ses_<id>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "klaxon.notify",
      "arguments": {
        "level": "info",
        "title": "Hello",
        "message": "Connected from curl"
      }
    }
  }'

Setting x-client-id ​

Klaxon attributes every item to the agent that created it via the x-client-id request header. The header is recommended (not required) — calls without one are bucketed under the literal string unknown. Pick a stable string per agent so the klaxon/agents resource and klaxon.list { agent_id } filter give you useful per-agent views.

bash
curl ... -H "x-client-id: my-deployment-bot" ...

The same x-client-id is the key for the per-agent rate limiter (60 calls/min default for tools/call; read methods are unmetered). Denied calls return JSON-RPC error -32003 with a retry_after_ms field.

Discover Endpoint ​

If you don't want to scrape stderr or open the Settings tab, the GET /mcp/discover endpoint returns the connection details without auth (prototype convenience):

bash
curl http://127.0.0.1:<port>/mcp/discover
# {"url":"/mcp","bearer":"mcp_...","protocol_version":"2025-03-26"}

You'll still need to know the port. The intended workflow is: launch Klaxon → open the Main window → ⚙ Settings → MCP → copy snippet.

Troubleshooting ​

"Unauthorized" / 401 The bearer token is missing or wrong. Copy a fresh one from the Main window's ⚙ Settings → MCP tab (or click "Refresh" to rotate it).

"Missing Mcp-Session-Id" / 400 You skipped the initialize step. Send initialize first, capture the Mcp-Session-Id response header, then include it on subsequent requests.

Connection refused Klaxon isn't running, or the port changed. Check the ⚙ Settings → MCP tab in the Main window for the current URL.

Tools list is empty Make sure your client sent notifications/initialized after initialize. Some MCP clients do this automatically.