Provides tools for interacting with Graylog, enabling log searching across streams, aggregating matches by field, discovering streams and fields, and fetching full log messages.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Graylog MCP Server Search for errors in payments namespace over the last 15 minutes."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A minimal MCP (Model Context Protocol) server in JavaScript that integrates with Graylog.
JavaScript MCP server
Tools: search (read matching log lines across multiple streams), analyze (aggregate matches by a field, with an optional time histogram), list_fields (which fields exist), list_streams (discover readable streams), and get_message (fetch one full document)
Empty results explain themselves. A zero-match search reports whether the query is wrong, the window is quiet, or Graylog simply hasn't indexed the logs yet — three causes that otherwise look identical and send an agent in circles
Discovery over guessing. list_fields and analyze's valueContains let an agent look up real field names and values instead of inventing them, since a wrong guess returns 0 hits and reads as "no logs exist"
Token-efficient by design, search returns a concise projection of high-signal fields by default; opt into full documents with verbose
A server-level "instructions" manual teaches the client the query syntax, stream-scoping rules, and severity quirks up front
Multi-instance support, query multiple Graylog servers from a single MCP server
Related MCP server: log-mcp
Node.js 18+
Configure one or more Graylog instances using numbered env vars:
Variable | Required | Description |
| yes | Graylog base URL for instance N |
| yes | API token for instance N |
| no | Human-readable label (default: |
Replace N with 1, 2, 3, … to register as many instances as needed. Only instances with both BASE_URL and API_TOKEN set will be active.
No installation needed, npx downloads and runs the server automatically.
claude mcp add graylog-mcp \
-e GRAYLOG_BASE_URL_INSTANCE_1=http://your-graylog-production.example.com:9000 \
-e GRAYLOG_API_TOKEN_INSTANCE_1=your_production_token \
-e GRAYLOG_LABEL_INSTANCE_1=production \
-e GRAYLOG_BASE_URL_INSTANCE_2=http://your-graylog-staging.example.com:9000 \
-e GRAYLOG_API_TOKEN_INSTANCE_2=your_staging_token \
-e GRAYLOG_LABEL_INSTANCE_2=staging \
-- npx -y @jperelli/graylog-mcp@latestOr add it manually to ~/.claude.json:
{
"mcpServers": {
"graylog-mcp": {
"command": "npx",
"args": ["-y", "@jperelli/graylog-mcp@latest"],
"env": {
"GRAYLOG_BASE_URL_INSTANCE_1": "http://your-graylog-production.example.com:9000",
"GRAYLOG_API_TOKEN_INSTANCE_1": "your_production_token",
"GRAYLOG_LABEL_INSTANCE_1": "production",
"GRAYLOG_BASE_URL_INSTANCE_2": "http://your-graylog-staging.example.com:9000",
"GRAYLOG_API_TOKEN_INSTANCE_2": "your_staging_token",
"GRAYLOG_LABEL_INSTANCE_2": "staging"
}
}
}
}Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"graylog-mcp": {
"command": "npx",
"args": ["-y", "@jperelli/graylog-mcp@latest"],
"env": {
"GRAYLOG_BASE_URL_INSTANCE_1": "http://your-graylog-production.example.com:9000",
"GRAYLOG_API_TOKEN_INSTANCE_1": "your_production_token",
"GRAYLOG_LABEL_INSTANCE_1": "production",
"GRAYLOG_BASE_URL_INSTANCE_2": "http://your-graylog-staging.example.com:9000",
"GRAYLOG_API_TOKEN_INSTANCE_2": "your_staging_token",
"GRAYLOG_LABEL_INSTANCE_2": "staging"
}
}
}
}Config file locations:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/claude-desktop/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use the same JSON structure shown above for Cursor.
Once configured, the tools become available and are called automatically when needed. The usual flow is to search the Default Stream (000000000000000000000001), which covers everything the token can read, then analyze to spot patterns, search to read individual lines, and get_message to inspect one hit in full. Reach for list_streams only to scope to a specific named stream. Example prompts:
Search Graylog for errors in the payments namespace in the last 15 minutes.
Query the "staging" instance.Which containers produced the most errors in the last hour?Which namespaces have "payments" in the name?Don't let the agent guess field names or values. A query on a field or value that doesn't exist matches nothing, which looks exactly like "there are no logs". list_fields answers which fields exist, and analyze with valueContains answers which values a field actually has.
List the streams the configured API token can read (id + title). Only readable ones are returned.
You usually don't need this: pass the Default Stream id 000000000000000000000001 to search/analyze to cover everything the token can read. A cluster can hold thousands of streams (the author's has 1,205), so output is capped — use titleContains when you want one specific named stream.
Parameters:
instance (string, optional): Label of the Graylog instance to query. Defaults to the first configured instance.
titleContains (string, optional): Case-insensitive substring filter on the stream title (e.g. catalogue).
limit (number, optional): Max streams to return. Default: 50. The Default Stream is always included and never counts against the cap.
List the message fields that actually exist in the index. Use it before searching on a field you haven't seen in a result, so you never guess a field name.
A cluster indexes thousands of fields (the author's: 3,269), and near-duplicates are common — namespace_name, Pod_namespace, pod_namespace and Namespace may all exist while only one is populated by your shipper. Pass contains to narrow.
Parameters:
contains (string, optional): Case-insensitive substring filter on the field name, e.g. namespace, pod, level.
limit (number, optional): Max field names to return. Default: 100.
instance (string, optional): Instance label. Defaults to the first configured instance.
Read matching log lines across one or more streams, merged newest-first. By default it returns a concise projection of high-signal fields (timestamp, source, level, container_name, pod_name, namespace_name, application_name, service, logger_name, name, msg, err, stack, message) plus each hit's _id/_index, with the raw message body truncated to 500 chars, this keeps the agent's context small. Set verbose: true (or pass explicit fields) to get every populated field, untruncated. Stream IDs are required, an all-streams search is not performed implicitly, because a limited-permission token would be rejected with 403 Not authorized.
name/msg/err/stack are there because a shipper that parses a JSON log line (pino, bunyan, structlog) extracts its keys into real fields. Those fields are the summary of the event, and they're cheap — the raw message body that contains them is neither, which is why it's truncated hard by default.
Reach for
analyzebeforesearch. Raw lines are the most expensive thing this server returns. A hundred repetitions of one error cost a hundred times as much viasearchas one aggregated row viaanalyze, and tell you less. Usesearchonce you know which line you want.
Tip: to search everything the token can see (including messages not routed to a named stream), pass the Default Stream id
000000000000000000000001.list_streamsalso surfaces it.
Parameters:
query (string, required): Search query, using Graylog/Elasticsearch syntax. Examples: msg:Error, namespace_name:app-payments-qa AND error, source:api-*, *.
streams (string, required): Comma-separated stream IDs to search. Get them from list_streams.
instance (string, optional): Label of the Graylog instance to query. Defaults to the first configured instance.
searchTimeRangeInSeconds (number, optional): Relative time range in seconds. Default: 900 (15 minutes).
from / to (string, optional): Absolute window in ISO-8601 UTC (e.g. 2026-07-11 14:00:00). When both are set they override the relative range, use them to investigate a known incident window.
searchCountLimit (number, optional): Max number of messages. Default: 50.
messageChars (number, optional): Max characters of the raw message body per hit. Default: 500. Raise it only when the detail you need lives in the raw body rather than the parsed fields.
verbose (boolean, optional): Return every populated field, untruncated, instead of the concise projection. Default: false.
fields (string, optional): Comma-separated explicit field list to return. Overrides the concise projection.
The response is { returned, total_matched, streams, messages, note?, projection?, why_no_results? }, where total_matched is the total number of hits across the streams (may exceed returned, which is capped by searchCountLimit); when it does, note explains how to see more.
When a search matches nothing, it tells you why. A bare total_matched: 0 is ambiguous, and the three causes need opposite responses, so why_no_results names the one that applies:
The window has messages, but none match. The streams and time range are fine, so the query is wrong — usually a guessed field name or value. Confirm with list_fields / analyze.
The window is empty, and indexing is current. These streams are genuinely quiet.
The window is empty, and the newest indexed message is hours old. Graylog is still indexing. The logs exist and have been received; they just aren't searchable yet. The response reports how far behind indexing is and the journal backlog. Don't conclude the logs are missing — widen the range or retry.
That last case is easy to misread as "this service produced no logs", and it's the reason this project exists in its current shape: the pipeline can lag ingestion by hours under load.
Note on log levels — severity must be discovered, not guessed. Some services emit a top-level Graylog
level(syslog: 3=error, 4=warn). Others log JSON, and the shipper extracts its keys into their own fields: pino's{"level":50,"msg":"Error","name":"SvcX"}typically becomes fieldsmsgandname, while its numericlevelis lost — it collides with the container's ownlevel(often7), solevel:50andlevel:ERRORboth match nothing even though the errors are plainly there. Guessing a disjunction likelevel:ERROR OR level:50 OR error OR exception OR fatalis how agents waste turns. Instead runlist_fields(contains: "level","msg","err"), thenanalyzeonmsgto see the actual values. Free-texterrorworks as a fallback; don't assumeexceptionorfatalexist. And avoid"level":50as a query, a quoted string before:is invalid Lucene.
Aggregate matching messages by the top values of a field instead of returning raw lines, e.g. which source, container_name, or level dominates the errors in a window. Optionally add a time histogram of total match volume. Two uses:
Find what is failing. Aggregate on a message field (msg, or whatever short summary field list_fields reveals) to collapse a thousand repetitions of one error into a single row with a count; on name / container_name / source to see who is emitting them. This is the fastest route from "is anything weird?" to an answer — and it costs a few hundred tokens where the equivalent search costs tens of thousands:
analyze field:msg → 1386 Error
60 rabbitmq pub/sub: publishing to …exchange failed
analyze field:name → 1290 CatalogueService
96 ShippingServiceDiscover a value before filtering on it. Set valueContains to find the exact name of a namespace/pod/service you only half-know. Elasticsearch rejects a leading wildcard, so namespace_name:*catalogue* is a hard error, not an empty result — this is the only way to substring-match a value.
Parameters:
field (string, required): Field to break down by, e.g. source, namespace_name, container_name, level. Confirm it exists with list_fields if you haven't seen it in a result.
streams (string, required): Comma-separated stream IDs, or the Default Stream id.
query (string, optional): Lucene filter applied before aggregating. Default: *.
valueContains (string, optional): Case-insensitive substring filter on the returned values, applied locally over a wide bucket scan.
instance (string, optional): Instance label. Defaults to the first configured instance.
searchTimeRangeInSeconds (number, optional): Relative range in seconds. Default: 900. Or use from/to for an absolute window.
size (number, optional): Number of top values to return. Default: 20.
histogramInterval (string, optional): One of minute, hour, day, week, month. When set, the response also includes a time histogram of match counts.
The response is { field, query, streams, total_matched, top_values: [{ value, count }], not_in_top_values, histogram?, note?, warning?, failed_streams?, why_no_results? }, where not_in_top_values counts matches that the returned values don't account for — messages with no value for the field, plus any bucket past the cut-off.
A stream the token can't read is skipped, not fatal: you get the aggregation over the readable streams plus failed_streams and a warning naming the ones excluded, in the same response.
Implemented on Graylog's Views/Aggregations API (
POST /api/views/search/sync), which takes every stream in a single request. The legacysearch/universal/*/termsand/histogramendpoints this originally used were removed in Graylog 6.0 and return404there.
Fetch the full, untruncated document for a single message by its _id and _index (both returned by search). Use it after a concise search to inspect one hit in detail without pulling every result verbose.
Parameters:
messageId (string, required): The _id from a search result.
index (string, required): The _index from a search result.
instance (string, optional): Instance label. Defaults to the first configured instance.
The tools here are shaped around published guidance on building MCP servers that AI agents can actually use well, rather than mirroring the Graylog REST API one endpoint at a time. The key ideas and where they come from:
Design for the agent's task, not the API surface, fewer, outcome-oriented tools. David Cramer (Sentry) makes the case that most MCP servers are still weak because they wrap raw endpoints instead of the jobs an agent needs to do; Sentry ships a curated, modest toolset instead. So this server exposes four task-shaped tools (discover → aggregate → read → drill in), not a wrapper per endpoint. , David Cramer, MCP Is Not Good Yet · Yes, Sentry has an MCP Server (…and it's pretty good)
Return high-signal context and protect the token budget. Anthropic's guidance is that tools should return concise, relevant results and support filtering/truncation/pagination rather than dumping raw data into the model's context. Hence search returns a concise projection by default (with verbose and get_message as opt-in escalation) and emits a note when results are capped.
, Anthropic, Writing effective tools for agents
Pair raw retrieval with an aggregation/analysis tool. New Relic's logging MCP does not only list log lines; it offers keyword search plus an analysis tool that surfaces error patterns and recurring issues. analyze fills that role for Graylog (top values of a field + optional histogram) so an agent can find patterns cheaply before reading individual lines.
, New Relic, MCP tool reference
Put the "user manual" in server instructions, not in every tool description. The MCP project recommends a top-level instructions field for cross-tool workflow, constraints, and quirks, keeping individual tool descriptions tight. This server's instructions teach the query syntax, the mandatory stream-scoping rule (a limited token gets 403 otherwise), and the pino numeric-severity gotcha once, up front.
, Model Context Protocol, Server Instructions: Giving LLMs a user manual for your server
Ensure at least GRAYLOG_BASE_URL_INSTANCE_1 and GRAYLOG_API_TOKEN_INSTANCE_1 are set.
Verify Node.js 18+ is installed.
Set DEBUG=true in the env to enable verbose logging to stderr.
Current implementation by Julian Perelli. Based on previous work from Leo Ruellas, lcaliani/graylog-mcp.
MIT
Aggregate matching messages by the top values of a field instead of returning raw lines. Optionally add a time histogram of match volume. Three main uses: (1) WHAT IS FAILING — aggregate on a message field (msg, or whatever short summary field list_fields reveals) to collapse a thousand repetitions of one error into one row with a count; on name/container_name/source to see who is emitting them. This is far cheaper and more informative than reading the same lines via search. (2) WHEN — set histogramInterval to see whether volume spiked. (3) DISCOVER A VALUE you are about to filter on — set valueContains to find the real name of a namespace/pod/service rather than guessing it (Elasticsearch rejects a leading wildcard, so field:*foo* is an error and this is the only way to substring-match a value). Pass streams:"*" to aggregate across every readable stream in one request — cheap here, and the reliable way to see a service whose stream removes its matches from the Default Stream.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Absolute window end, ISO-8601 UTC. Requires `from`. | |
| from | No | Absolute window start, ISO-8601 UTC (e.g. "2026-07-11 14:00:00"). Requires `to`. Overrides the relative range. | |
| size | No | Number of top values to return. Default: 20. | |
| field | Yes | Field to break down by, e.g. "source", "namespace_name", "container_name", "level". Confirm it exists with list_fields if you have not seen it in a result. | |
| query | No | Lucene query, e.g. "level:ERROR", "error OR exception", "source:api-*". Use "*" for everything. Default: "*". | |
| streams | Yes | Comma-separated Graylog stream IDs (from list_streams), or "*" for every stream the token can read. Required. Prefer "*" unless you already know the stream: the Default Stream ("000000000000000000000001") is NOT "everything" — most clusters route each service to its own stream that REMOVES its matches from the Default Stream, so searching only the Default Stream silently misses those services. | |
| instance | No | Graylog instance to query. Active: "instance_1". Default: "instance_1". | |
| valueContains | No | Case-insensitive substring filter on the returned VALUES, applied locally over a wide bucket scan. Use to find a value you only half-know, e.g. field:"namespace_name" valueContains:"catalogue" to learn the exact namespace before filtering on it. | |
| histogramInterval | No | If set, also return a time histogram of total match counts at this bucket size. | |
| searchTimeRangeInSeconds | No | Relative time range in seconds, ending now. Default: 900 (15 min). Ignored if from/to are set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden and does so admirably: it explains aggregation behavior, optional histogram, local substring filtering, and stream semantics, including the crucial caveat about the Default Stream and leading wildcard restrictions. It discloses these traits without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but exceptionally well-structured with numbered use cases, and every sentence serves a purpose—from explaining the main function to providing operational warnings. It is front-loaded with the core purpose and remains focused without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter tool with no output schema and no annotations, the description covers the essential operational context: what it does, when to use it, how parameters behave in practice, and caveats about streams and wildcard queries. It adequately compensates for missing structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description significantly enriches parameter understanding by tying valueContains to a discovery use case, histogramInterval to a timing use case, and field to a failure-analysis use case. It adds contextual meaning beyond the schema entries.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool aggregates matching messages by top field values rather than returning raw lines, with a specific verb-resource relationship. It further distinguishes itself from sibling tools like search by explaining it collapses repetitions into counts, making it more informative and cheaper.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly outlines three use cases (what is failing, when, discover a value) and directly contrasts with search ('far cheaper and more informative than reading the same lines via search'). It also provides guidance on when to use streams:"*" and warns against pitfalls like the Default Stream, offering clear situational advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full, untruncated document for a single message by its _id and _index (both returned by search). Use after a concise search to inspect one hit in full.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | The message _index from a search result. | |
| instance | No | Graylog instance to query. Active: "instance_1". Default: "instance_1". | |
| messageId | Yes | The message _id from a search result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the returned document is 'full, untruncated' unlike search results, but doesn't cover error behavior, auth requirements, or exact return structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences, front-loaded with action and resource. No redundant wording or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch operation with fully documented schema and clear usage guidance, the description is sufficient. It explains what the tool returns ('full document') and when to use it, making it complete without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters with descriptions. The description adds the crucial context that '_id' and '_index' are 'both returned by search', linking parameters to their source, which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch the full, untruncated document for a single message' with specific identifiers (_id and _index), distinguishing it from the sibling 'search' which returns concise results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use after a concise search to inspect one hit in full', providing a clear when-to-use. It does not mention exclusions or alternatives, but none are relevant among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the message fields that actually exist in the index. Use this BEFORE searching on a field you have not seen in a result, so you never guess a field name — a query on a nonexistent field returns 0 matches, which is indistinguishable from 'no logs'. Clusters index thousands of fields, so pass contains to narrow (e.g. "namespace").
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max field names to return. Default: 100. | |
| contains | No | Case-insensitive substring filter on the field name, e.g. "namespace", "pod", "level". | |
| instance | No | Graylog instance to query. Active: "instance_1". Default: "instance_1". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behavioral traits: it lists only fields that actually exist in the index, and warns about the misleading '0 matches' outcome. It also hints at the scale (thousands of fields). This is strong contextual disclosure, though it does not mention whether it is read-only or describe pagination, which would be nice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each serving a distinct purpose: stating the action, advising when to use, explaining the risk, and giving a usage suggestion. No fluff or redundancy. Well-structured with the primary action first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description provides sufficient context for an agent to decide when and how to invoke the tool. It covers the core use case, a critical pitfall, and parameter guidance. A small gap is the lack of detail about the return format or default behavior, but overall it is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context for 'contains' by explaining its purpose and giving an example. It also reinforces the rationale for using limit. This goes beyond just restating schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists actual indexed fields, which is distinct from sibling tools like search or analyze. It immediately identifies the resource (message fields) and the action (list), making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use before searching on unseen fields, explains the failure mode (0 matches indistinguishable from no logs), and advises using the contains parameter to narrow results. This provides clear when-to-use guidance versus search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Graylog streams the API token can read (id + title, and whether each removes its matches from the Default Stream). To search everything, pass streams:"*" to search/analyze rather than listing streams here. A cluster can hold thousands of streams, so results are capped — use titleContains to find one specific named stream (e.g. a service whose logs are absent from the Default Stream).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max streams to return. Default: 50. | |
| instance | No | Graylog instance to query. Active: "instance_1". Default: "instance_1". | |
| titleContains | No | Case-insensitive substring filter on the stream title. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full weight. It discloses that results are capped ('results are capped'), that the API token limits readability, and what the listing includes. It doesn't mention pagination or rate limits, but the key behavioral trait (cap) is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences. The first states purpose, the second gives an alternative, the third explains the cap and how to handle it. No wasted words, front-loaded, every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description sufficiently explains return content, the cap, the filtering option, and the relationship to search/analyze. It covers all essential context an agent needs to decide and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context beyond schema: explains why limit exists (thousands of streams), why titleContains is useful (capped results), and gives an example. This elevates it above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List the Graylog streams...') with the resource (Graylog streams) and the returned fields (id + title, and whether it removes matches from the Default Stream). It clearly distinguishes from siblings by steering users to search/analyze for searching everything.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use an alternative: 'To search everything, pass streams:"*" to search/analyze rather than listing streams here.' Also instructs to use titleContains for finding a specific named stream, with a concrete use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read individual matching log lines across one or more streams, merged newest-first. Returns a concise projection of high-signal fields by default (set verbose:true for all fields). Raw lines are expensive: if you want to know WHAT is failing rather than read specific lines, use analyze first — a hundred repetitions of one error cost a hundred times as much here as one aggregated count. Pass streams:"*" to cover every readable stream when you do not know which stream a service logs to (the Default Stream often excludes it).
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Absolute window end, ISO-8601 UTC. Requires `from`. | |
| from | No | Absolute window start, ISO-8601 UTC (e.g. "2026-07-11 14:00:00"). Requires `to`. Overrides the relative range. | |
| query | Yes | Lucene query, e.g. "level:ERROR", "error OR exception", "source:api-*". Use "*" for everything. | |
| fields | No | Comma-separated explicit field list to return. Overrides the concise projection. | |
| streams | Yes | Comma-separated Graylog stream IDs (from list_streams), or "*" for every stream the token can read. Required. Prefer "*" unless you already know the stream: the Default Stream ("000000000000000000000001") is NOT "everything" — most clusters route each service to its own stream that REMOVES its matches from the Default Stream, so searching only the Default Stream silently misses those services. | |
| verbose | No | Return every populated field (untruncated) instead of the concise projection. Default: false. | |
| instance | No | Graylog instance to query. Active: "instance_1". Default: "instance_1". | |
| messageChars | No | Max characters of the raw message body per hit. Default: 500. The parsed fields (msg, name, err) usually carry the summary already, so raise this only when the detail you need lives in the raw body. | |
| searchCountLimit | No | Max messages to return. Default: 50. | |
| searchTimeRangeInSeconds | No | Relative time range in seconds, ending now. Default: 900 (15 min). Ignored if from/to are set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses key traits: 'merged newest-first', concise projection vs verbose mode, the expensive nature of raw lines with cost implications, and important stream semantics (Default Stream often excludes services). While it does not mention pagination or rate limits, the cost warning and stream caveat add significant value beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficient. Every sentence adds value: purpose, projection behavior, cost warning, and stream guidance. It is front-loaded and not redundant, though the stream caution is somewhat lengthy. No wasted words, but it could be slightly more scannable. Still, it earns a 4.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no annotations, and no output schema, the description covers the critical context: when to use, how to avoid missing data, cost implications, and default behavior. It does not describe the exact return structure, but the concise-projection mention offers a hint. The absence of a return schema and the presence of sibling get_message mitigate this gap. Overall, a solid 4.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds strategic meaning for key params: verbose is tied to 'concise projection of high-signal fields', streams '*' is explained with the Default Stream caveat, and messageChars is contextualized as 'raw body vs parsed fields'. This goes beyond the schema's bare descriptions, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Read individual matching log lines across one or more streams, merged newest-first.' It clearly distinguishes the tool from siblings by explicitly recommending 'analyze' for aggregation and implying this is for reading specific lines. The resource (log lines) and operation (search/read) are clear, and the newest-first merge adds behavioral scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use and when-not-to-use guidance: 'if you want to know WHAT is failing rather than read specific lines, use analyze first' and explains the cost trade-off. It also provides a concrete strategy for stream selection ('Pass streams:"*" to cover every readable stream') and warns about the Default Stream pitfall, directly aiding the agent in choosing this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.3.0analyzeget_messagelist_fieldslist_streamssearchEach tool has a clearly distinct purpose: search returns raw log lines, analyze aggregates them, get_message fetches a full document, list_streams enumerates available streams, and list_fields enumerates available fields. Even though analyze and search both query messages, their descriptions make the difference unmistakable: one for counting/aggregating, one for reading individual lines.
All tool names use lowercase snake_case and begin with an imperative verb, which is predictable. The pattern is slightly mixed between bare verbs (search, analyze) and verb_noun compounds (list_streams, list_fields, get_message), but this is a minor deviation rather than a chaotic mix.
With 5 tools, the server is well-scoped for its purpose: querying logs, aggregating them, inspecting single messages, and discovering streams/fields. Each tool earns its place and there is no redundancy or bloat.
The tool surface covers the full read-only log analysis workflow: discover available fields and streams, search for raw messages, aggregate to find patterns, and drill into a specific message. There are no obvious dead ends, and the descriptions explicitly guide the agent on how to combine tools for effective use.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
The official MCP Server for the Mux API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jperelli/graylog-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
