Branch Diagnostics MCP
Click on "Deploy 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., "@Branch Diagnostics MCP Investigate why the branch office is slow."
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.
Branch Diagnostics MCP
An MCP server that turns a vague network complaint into a disciplined, AI-driven investigation.
"The branch office is slow." → a structured triage that pinpoints which hop is to blame — DNS, TCP, TLS, the server, or the link — and says what to do about it.
This server gives an AI assistant a set of tools to investigate service and network problems the way a seasoned engineer would: not by guessing, but by walking a deliberate funnel of evidence over cURL timing metrics.
The problem (why this exists)
When a user reports "the app is slow" or "the branch can't connect," the complaint is vague but the cost is real: time-to-resolution. Good triage is slow, inconsistent, and locked in the heads of a few senior engineers — everyone else gathers the wrong data, reads it the wrong way, and escalates.
The expertise that makes triage fast is actually quite structured: for this kind of symptom, look at these specific signals, in this order, and here's what "bad" looks like. That structure can be encoded once and handed to an AI assistant — so anyone, at any hour, runs the same rigorous investigation. That's what this project does.
What's MCP? The Model Context Protocol is an open standard (introduced by Anthropic in late 2024) for giving AI assistants real tools and data through a uniform interface. An MCP server like this one exposes capabilities; any MCP client (Claude Desktop, IDEs, agents) can use them. This project was first built in June 2025, in MCP's earliest months — see Evolution below.
Related MCP server: Wireshark MCP Server
What it does — the funnel
A single coherent workflow, each step a tool the assistant can call:
flowchart LR
S["Symptom<br/>(free text)"] --> C["1 · Categorize<br/>diagnostic_categorize"]
C --> M["2 · Pick metrics<br/>find_metrics"]
M --> D["3 · Collect data<br/>get_data_metrics"]
D --> A["4 · Analyse<br/>analyse"]
A --> R["Severity + anomalies<br/>+ recommendations"]The assistant is also given a guidance prompt that teaches it how to run the funnel, and two resources it can browse: the catalog of diagnostic categories and the catalog of metrics.
Architecture & design decisions
Why cURL metrics are the right signal
CURLINFO_* values are libcurl's per-request timing and outcome
breakdown — the same data you can see with curl -w. Every HTTP request passes through ordered
phases, and libcurl reports a cumulative timestamp at each one. The power is in the differences
between adjacent phases: each gap isolates one stage of the request, so a single slow request tells
you exactly which hop is at fault.
Phase gap | cURL metric math | What it isolates |
DNS resolution |
| Name servers / resolver |
TCP connect |
| Network path, routing, latency |
TLS handshake |
| Certificates, TLS negotiation |
Server think-time (TTFB) |
| The application / backend |
Content download |
| Throughput, payload size, link |
Alongside timing, outcome metrics (RESPONSE_CODE, SSL_VERIFYRESULT, OS_ERRNO,
NUM_CONNECTS, …) catch failures rather than slowness. Together they cover the two questions every
triage starts with: is it slow, or is it broken — and where?
The MCP surface
Tools (all read-only, annotated as such):
Tool | Funnel step | In → Out |
| 1 · classify |
|
| 2 · select |
|
| 3 · collect |
|
| 4 · evaluate |
|
Resources (browsable JSON, with parameterized lookups):
branch://categories, branch://categories/{name}, branch://metrics, branch://metrics/{name}.
Prompt: branch_diagnostics_guidance — reusable system guidance that teaches a client to drive
the funnel (the diagnostic methodology, not just the tool list).
Design decisions worth calling out
Structured, typed tool output. Tools return typed dataclasses, so the server emits machine- readable
structuredContentwith an auto-generatedoutputSchema— clients get data, not prose to re-parse. (The original prototype returned hand-formatted Markdown; this is the meaningful upgrade.)A registered guidance prompt. The diagnostic methodology ships with the server as a first-class MCP prompt, instead of living in a comment.
Read-only by contract. Every tool is annotated
readOnlyHint, so clients know it's safe to call.A pluggable data layer.
MetricsDataSourceis isolated behind one seam. It simulates realistic data today (so the server runs out of the box); a real backend drops in without touching any diagnostic logic — see Going to production.Vendor-neutral by design. Pure libcurl + observability vocabulary; nothing tied to any product.
Worked example
Driving the funnel for "branch office VPN connectivity problems" (actual server output):
1 · diagnostic_categorize("branch office vpn connectivity problems")
→ recommended_category: "Branch Office Issue" (confidence 3)
2 · find_metrics("branch office vpn connectivity problems", "Branch Office Issue")
→ CURLINFO_NAMELOOKUP_TIME, CURLINFO_CONNECT_TIME, CURLINFO_LOCAL_IP,
CURLINFO_PRIMARY_IP, CURLINFO_TOTAL_TIME (each with a relevance note)
3 · get_data_metrics([...], "branch-paris-01")
→ { "CURLINFO_CONNECT_TIME": { current: 0.125, threshold_warning: 0.5, ... }, ... }
simulated: true
4 · analyse("branch office vpn connectivity problems", "Branch Office Issue", <data>)
→ overall_severity: "NORMAL"
analysis_summary: "No significant anomalies detected ..."
next_steps: [ "Monitor the identified metrics over time ...", ... ]Feed analyse data where, say, CURLINFO_CONNECT_TIME exceeds its critical threshold and the verdict
flips to CRITICAL with a targeted recommendation — the network hop, not the server, is implicated.
Install & run
Requires Python ≥ 3.13 and uv.
uv venv
uv pip install -e .Run it (stdio is the default transport, ideal for local MCP clients):
uv run python branch_diagnostics_server.py
# or via the FastMCP CLI:
uv run fastmcp run branch_diagnostics_server.pyRun it over Streamable HTTP instead:
MCP_HTTP=1 uv run python branch_diagnostics_server.py # serves on http://127.0.0.1:8000/mcpRegister it with an MCP client (e.g. Claude Desktop) by adding to the client's config:
{
"mcpServers": {
"branch-diagnostics": {
"command": "uv",
"args": ["run", "python", "branch_diagnostics_server.py"],
"cwd": "/path/to/branch_mcp_v2"
}
}
}Smoke-test the whole funnel in-memory (no network):
uv run python tests/smoke_test.pySimulated data — going to production
get_data_metrics returns simulated values by default (the response carries simulated: true), so
the server is useful immediately. The data layer is deliberately isolated in a single class,
MetricsDataSource. To go live, implement one that reads real measurements — from a synthetic-probe /
active-test result store, a time-series database, or an observability backend — and the four tools, the
analysis, and the schemas all keep working unchanged.
Evolution
This is the 2026 modernized successor to a prototype I built in June 2025, during MCP's first
months: branch_MCP (its commit history dates the work).
The diagnostic idea held up; the platform moved on. v2 brings it current:
v1 (Jun 2025) | v2 (2026) | |
Framework | FastMCP 2.8 (now EOL) | FastMCP 3.4 |
Tool output | hand-formatted Markdown strings | typed, structured |
Guidance prompt | a dead variable, never registered | a registered MCP prompt |
Tool metadata | none | read-only annotations |
Resources | two flat JSON blobs | + parameterized templates |
Data layer | inline simulator | pluggable |
Taken together, the pair is a small, honest record of spotting a protocol early, shipping a real solution to a real triage problem, and keeping the craft current as the ecosystem matured.
License
MIT.
Available Tools
4 toolsanalyseAnalyse metric dataARead-only
Step 4 of the funnel: evaluate collected metric data against thresholds, surface anomalies with severities, and return recommendations and next steps.
Inputs: symptom (required), category (required), data_metrics (required). Returns: Output of `analyse`.
diagnostic_categorizeCategorize symptomARead-only
Step 1 of the funnel: classify a free-text symptom into the most likely diagnostic category, with a confidence score and the scores for every category.
Inputs: symptom (required). Returns: Output of `diagnostic_categorize`.
find_metricsFind relevant metricsARead-only
Step 2 of the funnel: for a symptom and category, return the cURL metrics most worth collecting, each with its definition and why it is relevant.
Inputs: symptom (required), category (required). Returns: Output of `find_metrics`.
get_data_metricsGet metric dataARead-only
Step 3 of the funnel: fetch current values, rolling averages, and thresholds
for the given metrics at a location. Data is simulated by default (simulated
is true); swap the data source for a real backend in production.
Inputs: metrics (required), location (required). Returns: Output of `get_data_metrics`.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool represents a distinct step in the diagnostic funnel: categorize, find metrics, get data, and analyse. Their purposes are clearly separated with no overlap.
Naming is inconsistent: three tools follow a verb_noun pattern (diagnostic_categorize, find_metrics, get_data_metrics) but 'diagnostic_categorize' anomalously includes a prefix, and 'analyse' is just a verb without a noun, breaking the pattern.
With 4 tools, the server is appropriately scoped for a focused diagnostic pipeline. Each tool serves a clear purpose without redundancy.
The four tools cover the entire diagnostic funnel from symptom categorization to analysis and recommendations. Minor gaps like a reset or overview tool are not needed for the core workflow.
Related MCP Connectors
Network, domain and website diagnostics for AI clients via MCP.
AI-powered incident management and server monitoring via MCP.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Related MCP Servers
AlicenseNot gradedqualityAmaintenanceMCP server that gives AI assistants impact analysis, cross-project reference tracking, and code health scoring.172 PyPI4Apache 2.0- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server that provides AI assistants with professional-grade network analysis capabilities, combining Wireshark packet analysis, nmap scanning, and threat intelligence for enhanced network troubleshooting and security analysis.MIT
- FlicenseNot gradedqualityCmaintenanceMCP server that enables AI agents to programmatically run tests, query results, and receive intelligent recommendations about test execution strategy.-
- AlicenseAqualityDmaintenanceAn MCP server that exposes live network monitoring data as Resources and diagnostic capabilities as Tools, letting AI assistants query network health conversationally.6MIT