troubleshooting

Graylog MCP — Troubleshooting

Use this skill when Graylog MCP tool calls fail or return nothing unexpectedly.

Step 1 — Always start with get_system_info

If any other tool fails, call get_system_info first. It tells you whether the server is reachable and the credentials are valid. If it returns successfully, the connection is fine and the issue is in the query.

If get_system_info itself fails, work through Steps 2–4 below.

Step 2 — BASE_URL checks

The BASE_URL env var must:

• Include the scheme: https://graylog.example.com (or http:// for local).
• Not end with /api or a trailing slash. The server adds the API path.
• Be reachable from the host running the MCP server (not from the user's laptop, if those differ).

Verify reachability:

curl -fsS -o /dev/null -w "%{http_code}\n" "$BASE_URL/api/system" -u "$API_TOKEN:token" && echo OK

If curl returns 200, the URL and token both work; the MCP server itself is misconfigured. If curl fails, it is a network / auth problem.

Step 3 — API_TOKEN checks

• Tokens are generated in the Graylog UI under Account → Edit profile → Create token.
• Auth uses the token as the username and the literal string token as the password (Graylog convention). Confirm the MCP server's HTTP basic auth header reflects this.
• Tokens can expire or be revoked. If curl returns 401 with a known-good URL, regenerate the token.

Step 4 — HTTP status → fix mapping

Status	Meaning	Fix
401	Token invalid / expired	Regenerate token, update API_TOKEN.
403	Token valid, lacks scope	Ask the Graylog admin to grant read access to the streams you need.
404 on stream filter	Stream ID doesn't exist or token can't see it	Call list_streams to confirm valid IDs visible to this token.
5xx	Graylog server-side issue	Not the MCP server's fault. Check Graylog itself.

Step 5 — Empty results when results are expected

If a search returns zero hits but you know logs exist:

• Time zone. Graylog stores UTC. If you pass from/to as local-time ISO strings without a UTC offset, you may be querying the wrong window. Always use Z-suffixed UTC.
• Query syntax. Elasticsearch query string, not pure Lucene. field=value won't work; use field:value. AND/OR must be uppercase.
• Field casing. Field names are case-sensitive. service:foo ≠ Service:foo.
• Stream filter mismatch. If you pass a streamId the token can't read, you get an empty (not an error) response.

Step 6 — list_streams returns empty

The token has no stream-read permissions. Ask the admin to grant read access; the MCP server itself is fine.

When to give up and ask

If steps 1–5 all check out and the tool still fails, the problem is on the Graylog server side (cluster issue, indexer down, retention purge). Surface what you've verified and ask the user to check with their Graylog operator or check the Graylog /api/system/cluster/health endpoint directly.