Skip to main content
Glama
CodeWithEhtisham

netdiag-mcp

by CodeWithEhtisham
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

netdiag-mcp

An MCP server that gives an AI agent read-only network diagnostics for a target host: DNS, TLS, HTTP and registry data.

Agents are good at reasoning about infrastructure problems and bad at gathering the facts. "Why is this domain not loading?" needs a resolver, a certificate, a redirect chain and a registry lookup — four different tools, none of which an LLM can do on its own. This server supplies them.

No API keys. Every backing service is keyless, so it runs the moment you clone it.

Install and run

uv sync
uv run netdiag-mcp        # speaks MCP over stdio

Register it with any MCP client. For Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "netdiag": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/netdiag-mcp", "netdiag-mcp"]
    }
  }
}

Related MCP server: External Reconnaissance MCP Server

Tools

Tool

Answers

Backed by

dns_lookup(domain, record_type)

What does this resolve to? A/AAAA/MX/TXT/NS/CNAME/SOA/CAA, with TTLs.

Cloudflare DNS-over-HTTPS

tls_certificate(host, port)

Who issued the cert, when does it expire, which SANs, which TLS version?

Python ssl

http_probe(url)

Where does this redirect to, how slow is each hop, which security headers are missing?

httpx

ip_rdap(ip)

Who owns this address, which allocation, which country?

RDAP registries

Each is annotated readOnlyHint so a client can auto-approve it safely.

Design notes

NXDOMAIN is a result, not an error. dns_lookup returns {"nxdomain": true, "records": []}. "This domain does not exist" is usually the answer the agent wanted, and burying it in an exception makes it harder to reason about.

A failed certificate check is also a result. tls_certificate returns valid: false with the verification message rather than raising — an expired or mismatched cert is frequently the thing being investigated.

Errors come back as {"error": ...}. A tool call that raises gives an agent nothing to work with. Every failure path returns a dict describing what went wrong.

Security

These tools accept a hostname from a language model and then make a network request to it. That is a textbook SSRF surface: without a guard, an agent could be talked into using this server to reach 169.254.169.254 (cloud metadata), 127.0.0.1, or anything on an internal RFC1918 network.

resolve_public() resolves the target and refuses it unless every returned address is publicly routable. Checking every answer matters — a hostile domain can return one public and one private record and win the race if only the first is inspected.

Three details that are easy to get wrong, and are covered by tests:

  • Redirects are re-checked at every hop. A public URL is allowed to redirect to 127.0.0.1. Following redirects with follow_redirects=True would validate only the first URL, so the chain is walked by hand.

  • Opaque schemes. data: and javascript: contain no ://, so a check for :// misses them entirely.

  • example.com:8080 is not a scheme. URL scheme grammar permits dots, so a bare host:port matches the scheme pattern exactly and must not be rejected as one.

Tests

uv run pytest -m "not integration"   # 62 offline tests
uv run pytest                        # adds 3 that need the network

Validation and the SSRF guard are tested offline on purpose: they are the parts that must not regress, and they should not need a working internet connection to verify.

Requirements

Python 3.12+, mcp>=2.0. Note that MCP SDK 2.0 renamed FastMCP to MCPServer; this targets the 2.x API.

Licence

MIT

Available Tools

4 tools
dns_lookupDNS lookupA
Read-only

Resolve a DNS record for a domain over DNS-over-HTTPS. Returns the records with TTLs; NXDOMAIN is reported as an empty result, not an error.

ParametersJSON Schema
NameRequiredDescriptionDefault
domainYesDomain name, e.g. example.com
record_typeNoDNS record typeA

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare read-only and non-destructive behavior, but the description adds valuable behavioral details beyond that: it returns TTLs and reports NXDOMAIN as an empty result rather than an error. This enriches the agent's understanding of the tool's runtime behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exceptionally concise — two short sentences — yet conveys all essential information: the action, target, method, and key behavioral notes. There is no redundancy or extraneous detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simple nature, the description is complete. It covers what the tool does, how it behaves on success and failure (NXDOMAIN), and what the return contains (TTLs). No additional context is needed for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema is fully covered with descriptions for both parameters (domain and record_type), including an enum for record_type and a default. The description does not add significant semantic information beyond what the schema already provides, so it meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action — resolving a DNS record — and the resource (a domain) via DNS-over-HTTPS. It also clarifies the return format (records with TTLs) and edge-case behavior (NXDOMAIN as empty result), leaving no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear context for when to use the tool (for DNS record resolution) but does not explicitly compare it to the sibling tools (tls_certificate, http_probe, ip_rdap) or state when not to use it. The context is sufficient to infer appropriate usage, though explicit exclusions would make it stronger.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

http_probeHTTP probeA
Read-only

Follow a URL's redirect chain and report each hop, the final status, response timing, and which common security headers are present or missing.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesURL or bare hostname; https:// is assumed if omitted

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only/open-world safety. The description adds behavioral transparency by stating it follows redirects and may make HTTP requests to a given URL, with no side effects indicated, and the param note clarifies scheme defaulting.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one tightly worded sentence that front-loads the action and enumerates the key outputs. The parameter note is also concise and useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a probe tool with an output schema and read-only annotations, the description covers the key behavioral context: redirects, final status, timing, and security headers. No major gaps are visible.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The url parameter is fully described, including that bare hostnames are accepted and https:// is assumed when no scheme is provided. This adds meaning beyond the schema, which only names the parameter and marks it required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as an HTTP probe that follows redirects and reports status, timing, and security headers. This is specific enough to distinguish it from the DNS, TLS, and RDAP siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The use case is implied by the description—investigating HTTP endpoint responses and security headers—but it gives no explicit guidance about when to choose this over dns_lookup, tls_certificate, or ip_rdap, nor any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ip_rdapIP registry lookupA
Read-only

Look up an IP address in the regional registry via RDAP: allocation handle, network range, country, and responsible organisations.

ParametersJSON Schema
NameRequiredDescriptionDefault
ipYesPublic IPv4 or IPv6 address

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds little behavioral detail beyond stating the operation type. No additional side effects, rate limits, or failure modes are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that front-loads the primary action and lists the key output fields. It contains no filler or redundancy, making it highly concise and efficiently structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple lookup tool, the description provides sufficient context: it names the protocol (RDAP), the input type (IP address), and the output fields. The sibling tools are clearly different network operations, so no additional context is needed for selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The sole parameter 'ip' is described as 'Public IPv4 or IPv6 address', which fully covers the schema (100% coverage). However, the description does not add extra meaning beyond the schema, so it remains at the baseline for full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'look up' and the resource 'IP address in the regional registry via RDAP', and enumerates the returned information (allocation handle, network range, country, responsible organisations). It is easily distinguishable from sibling tools like dns_lookup, tls_certificate, and http_probe.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when IP registry information is needed, but does not explicitly state when to use this tool versus alternatives or when not to use it. There is no mention of scenarios where other sibling tools would be more appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tls_certificateTLS certificateA
Read-only

Inspect the TLS certificate a host serves: issuer, subject, SANs, validity window, days until expiry, and negotiated protocol. A failed chain verification is returned as valid=false with the reason.

ParametersJSON Schema
NameRequiredDescriptionDefault
hostYesHostname, e.g. example.com
portNoTCP port

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true and destructiveHint=false, covering safety. The description adds valuable behavioral context by disclosing that failed chain verification returns valid=false with the reason, which goes beyond the structured annotations. It also lists the negotiated protocol, a behavioral output. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with zero wasted words. The primary purpose and specific outputs are front-loaded, and the failure behavior is appended as a separate sentence. It is efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema, so return values are documented there and the description need not repeat them. The description covers the essential behavioral aspects (what it inspects, failure handling) and the annotations cover safety. Complexity is low (two parameters), and nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (both host and port have descriptions), so baseline is 3. The tool description does not add further parameter semantics beyond what the schema already provides. It mentions 'host' implicitly but does not elaborate on format or constraints beyond the schema's examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Inspect') with a clear resource ('TLS certificate a host serves') and enumerates the exact fields returned (issuer, subject, SANs, validity window, days until expiry, negotiated protocol). It also states failure behavior. This clearly distinguishes it from sibling tools (dns_lookup, http_probe, ip_rdap) which cover DNS, HTTP, and IP info respectively.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (when TLS certificate details are needed) and its sibling set makes alternatives obvious. However, it does not explicitly state when not to use it or name alternatives as the calibration example does. The domain is clear enough that an agent can infer correct usage without exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observeddns_lookup
    • First observedhttp_probe
    • First observedip_rdap
    • First observedtls_certificate
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a distinct aspect of network diagnostics: DNS lookup, TLS certificate inspection, HTTP probing, and IP RDAP lookup. There is no functional overlap between them.

Naming Consistency5/5

All tool names use a consistent lowercase_with_underscores convention (dns_lookup, tls_certificate, http_probe, ip_rdap), making them predictable and easy to parse.

Tool Count5/5

With 4 tools, the set is well-scoped for a network diagnostic server, fitting the typical 3-15 range comfortably without being too sparse or overwhelming.

Completeness4/5

The tool set covers common network diagnostics (DNS, TLS, HTTP, IP), but might omit tools like ping or traceroute. However, the included coverage is coherent and meets the obvious intended purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers