MCP Server

The desktop app includes an MCP (Model Context Protocol) server so AI coding assistants can read your logs.

Auto-registration with Claude Code

If you have the claude CLI installed, the desktop app registers the MCP server with it automatically on launch — no config file to write. On startup, Gunsole runs:

claude mcp add gunsole --transport http http://localhost:17655/mcp --scope user

This is best-effort: if the claude CLI isn’t found on your machine, the app just skips it. When it succeeds, gunsole shows up as an available MCP server for Claude Code everywhere, with nothing to configure per-project. You can check registration status in the desktop app under Settings → About, which shows whether the claude CLI was detected and whether registration succeeded.

Once registered, ask Claude Code about your logs directly:

"Check my app's error logs from the last hour"
"What are the most common error patterns in the auth bucket?"
"Show me the latest fatal logs across all projects"

Endpoint

POST http://localhost:17655/mcp

JSON-RPC 2.0 protocol over Streamable HTTP.

Available tools

`list_projects`

List all projects with IDs, names, and workspace assignments.

{ }

`list_buckets`

List buckets for a specific project.

{ "projectId": "my-app" }

`query_logs`

Query logs with full filter support.

{
  "projectId": "my-app",
  "level": "error,warn",
  "bucket": "auth,payments",
  "search": "failed",
  "tags": { "env": ["prod"], "action": ["login", "signup"] },
  "limit": 50,
  "since": 1708000000000,
  "until": 1708100000000
}

Parameter	Type	Description
`projectId`	string	Required. Project ID.
`level`	string	Comma-separated levels: `error`, `warn`, `info`, `debug`, `fatal`.
`bucket`	string	Comma-separated bucket names.
`search`	string	Substring search in log messages.
`tags`	object	Tag filters as `{key: [values]}`. Logs must match ALL keys, any value per key.
`limit`	integer	Max logs to return (default 50, max 200).
`since`	integer	Epoch ms — only logs after this timestamp.
`until`	integer	Epoch ms — only logs before this timestamp.

`tail_logs`

Get the latest logs across ALL projects. Useful when you don’t know the project ID.

{ "limit": 20, "level": "error" }

Parameter	Type	Description
`limit`	integer	Max logs (default 20, max 100).
`level`	string	Comma-separated levels to filter.

Manual setup

For other MCP clients, or if auto-registration doesn’t apply to you (no claude CLI, project-scoped config, etc.), point your client at the endpoint directly.

For Claude Code, add to your project’s .mcp.json:

{
  "mcpServers": {
    "gunsole": {
      "type": "streamableHttp",
      "url": "http://localhost:17655/mcp"
    }
  }
}

Any MCP client that supports Streamable HTTP transport can connect the same way — point it at http://localhost:17655/mcp.

Protocol

Standard JSON-RPC 2.0:

// Initialize
{"jsonrpc": "2.0", "method": "initialize", "id": 1}

// List tools
{"jsonrpc": "2.0", "method": "tools/list", "id": 2}

// Query logs
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 3,
  "params": {
    "name": "query_logs",
    "arguments": {
      "projectId": "my-app",
      "level": "error",
      "limit": 20
    }
  }
}