needle-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| NEEDLE_MCP_CONFIG_DIR | No | Directory containing adapters.yaml and topology.yaml. Falls back to CLAUDE_PROJECT_DIR then process cwd if not set. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| correlate_idsB | Extract and rank correlation IDs (request/trace/span/message/job) shared across log snippets you've already collected elsewhere. Use this to carry an identifier forward across a sync-to-async hop (e.g. an HTTP request into a Kafka consumer). |
| plan_investigationA | START HERE when the user hands you a bare identifier — a session id, request id, trace id, or correlation id — with no logs yet. Classifies the identifier's shape, returns every vendor spelling it may appear under, names which configured sources and coverage surfaces can answer for it, and suggests a time window (widened when the id looks async). Use correlate_ids instead once you already have log snippets in hand. |
| analyze_visual_evidenceA | Extract structured evidence from a HAR / browser network-tab export: failed and slow requests, with correlation headers, redacted. If you already have a screenshot in your own context, reason about it directly — do NOT pass it here. The image_base64 parameter returns the image unchanged (this tool runs no vision model), so round-tripping one you can already see just puts a second copy in your context. Pass it only if you need the image echoed back alongside HAR findings. |
| query_generic_sourceA | Query a source declared in adapters.yaml via a config-templated REST call. Use ONLY when no vendor MCP (Datadog/Splunk/Loki/etc.) already covers this source — prefer your own connected MCPs first. |
| list_generic_sourcesB | List the sources declared in adapters.yaml for this deployment. |
| get_coverageA | Look up which observability surfaces cover (or are blind to) a resource type, from topology.yaml. If unknown_coverage is true, you may NOT conclude absence from an empty query result for this resource type. |
| validate_rcaA | Deterministically lint a draft RCA's structured claim before you post it. Call this before finalizing any RCA, and emit the envelope fenced between BEGIN_NEEDLE_MCP_RESULT_JSON and END_NEEDLE_MCP_RESULT_JSON — on Claude Code a Stop hook re-runs this check against that block regardless. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| rca_methodology | The full needle-mcp investigation discipline: the five rules, the environment/coverage gates, and the exact RCA result envelope schema. Read this before using any needle-mcp tool. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| rca_methodology | The full needle-mcp investigation discipline and RCA result envelope schema (skills/rca-methodology/SKILL.md). |
TDQS
Scored across 7 tools
Each tool targets a distinct stage of the investigation workflow: plan_investigation starts from a bare identifier, correlate_ids handles already-collected snippets, generic source query/list handle adapter access, get_coverage handles topology, analyze_visual_evidence handles HAR, and validate_rca handles output. The only near pair is explicitly disambiguated in the descriptions.
All tool names follow a consistent verb_noun snake_case pattern (plan_investigation, query_generic_source, list_generic_sources, validate_rca). There is no style mixing or vague verb usage.
Seven tools is a well-scoped set for an observability/RCA investigation server. Each tool maps to a distinct workflow step without redundancy or bloat.
The tool surface covers the full investigation lifecycle: identifying a trace ID, querying sources, listing sources, checking coverage, correlating IDs across snippets, analyzing HAR evidence, and validating the final RCA. Vendor-specific log retrieval is intentionally deferred to connected MCPs, so there is no obvious dead-end in the intended workflow.