How do I use Branch Diagnostics MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

by Fromzy1

Overview Schema Source Related Servers Discussions Admin

Python

Remote

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	`NAMELOOKUP_TIME`	Name servers / resolver
TCP connect	`CONNECT_TIME − NAMELOOKUP_TIME`	Network path, routing, latency
TLS handshake	`PRETRANSFER_TIME − CONNECT_TIME`	Certificates, TLS negotiation
Server think-time (TTFB)	`STARTTRANSFER_TIME − PRETRANSFER_TIME`	The application / backend
Content download	`TOTAL_TIME − STARTTRANSFER_TIME`	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
`diagnostic_categorize`	1 · classify	`symptom` → best category + confidence + all scores
`find_metrics`	2 · select	`symptom, category` → the metrics to collect, each with why
`get_data_metrics`	3 · collect	`metrics, location` → current values, rolling stats, thresholds
`analyse`	4 · evaluate	`symptom, category, data` → severity, anomalies, recommendations

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 structuredContent with an auto-generated outputSchema — 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. MetricsDataSource is 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.py

Run it over Streamable HTTP instead:

MCP_HTTP=1 uv run python branch_diagnostics_server.py   # serves on http://127.0.0.1:8000/mcp

{
  "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.py

Simulated 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 `outputSchema`
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 `MetricsDataSource` seam

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 tools

analyseAnalyse metric dataA

Read-only

Step 4 of the funnel: evaluate collected metric data against thresholds, surface anomalies with severities, and return recommendations and next steps.

ParametersJSON Schema

Name	Required	Description
`symptom`	Yes	Free-text description of the network/service issue.
`category`	Yes	The diagnostic category under investigation.
`data_metrics`	Yes	The output of get_data_metrics (or a {metric: {...}} mapping).

Output Schema

ParametersJSON Schema

Name	Required	Description
`symptom`	Yes
`category`	Yes
`overall_severity`	Yes
`analysis_summary`	Yes
`anomalies`	Yes
`recommendations`	Yes
`next_steps`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

Annotations provide readOnlyHint: true, and the description's actions ('evaluate', 'surface anomalies') are consistent with a read-only analysis. The description adds behavioral details like returning recommendations and next steps, which goes beyond the annotation alone.

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, concise sentence that front-loads the funnel step and clearly conveys all necessary information without any extraneous words.

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

Completeness4/5

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

Given the presence of an output schema, the description adequately explains the tool's role, inputs, and outputs. It provides step context and mentions the return of recommendations and next steps, making it effectively complete for an analysis tool.

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

Parameters4/5

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

Schema coverage is 100%, but the description adds context by noting that 'data_metrics' is the output of 'get_data_metrics'. This helps the agent understand the expected input format beyond the schema's generic description.

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 specific verbs ('evaluate', 'surface', 'return') and identifies the resource ('metric data'). It explicitly labels itself as 'Step 4 of the funnel', distinguishing it clearly from siblings like 'diagnostic_categorize', 'find_metrics', and 'get_data_metrics'.

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 positions the tool as part of a sequential funnel ('Step 4'), implying it should be used after prior steps. However, it does not explicitly state when not to use it or what alternatives exist beyond the sibling names.

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

diagnostic_categorizeCategorize symptomA

Read-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.

ParametersJSON Schema

Name	Required	Description	Default
`symptom`	Yes	Free-text description of the network/service issue.

Output Schema

ParametersJSON Schema

Name	Required	Description
`symptom`	Yes
`recommended_category`	Yes
`confidence_score`	Yes
`category_description`	Yes
`all_scores`	Yes

TDQS

A4.3/5.0

Behavior4/5

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

Annotations declare readOnlyHint=true, consistent with a classification read operation. The description adds behavioral detail: returns a confidence score and scores for every category, beyond what annotations provide.

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 sentence that is front-loaded with key information ('Step 1 of the funnel') and includes all necessary details without any wasted words.

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 low complexity (1 parameter, output schema exists), the description adequately covers what the tool does, including the output (confidence score and per-category scores). It is complete for its purpose.

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 coverage is 100% for the single parameter 'symptom' with a clear description. The tool's description does not add extra parameter meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.

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 action (classify), the input (free-text symptom), and the output (diagnostic category with confidence and per-category scores). It positions itself as 'Step 1 of the funnel,' distinguishing it from sibling tools like analyse or find_metrics.

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 explicitly says 'Step 1 of the funnel,' indicating when to use it (as a first step). However, it does not provide when-not-to-use guidance or mention alternatives, though the sibling tools imply a pipeline.

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

find_metricsFind relevant metricsA

Read-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.

ParametersJSON Schema

Name	Required	Description	Default
`symptom`	Yes	Free-text description of the network/service issue.
`category`	Yes	One of the diagnostic categories (see the branch://categories resource).

Output Schema

ParametersJSON Schema

Name	Required	Description
`symptom`	Yes
`category`	Yes
`recommended_metrics`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

Annotations indicate readOnlyHint=true, and the description aligns by stating the tool returns metrics. It adds value by detailing output content (definitions, relevance), but does not discuss potential behavioral traits like rate limits or permissions.

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 concise sentence that front-loads the funnel context and directly states the tool's action, with no unnecessary words.

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 low complexity (2 simple parameters), full schema coverage, and an output schema, the description sufficiently covers the tool's purpose and expected behavior without gaps.

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

Parameters4/5

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

Schema description coverage is 100% with clear definitions for symptom and category. The description adds context about the tool's purpose and output, but does not elaborate on parameter semantics beyond what the schema provides.

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 tool's function: given a symptom and category, return relevant cURL metrics with definitions and reasons. It positions itself as 'Step 2 of the funnel', distinguishing it from siblings like 'diagnostic_categorize' and 'get_data_metrics'.

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 usage context by referencing 'Step 2 of the funnel' and requiring symptom and category inputs, but it does not explicitly state when not to use it or compare with siblings beyond context clues.

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

get_data_metricsGet metric dataA

Read-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.

ParametersJSON Schema

Name	Required	Description	Default
`metrics`	Yes	cURL metric names to collect (e.g. from find_metrics).
`location`	Yes	Network location or endpoint to gather metrics from.

Output Schema

ParametersJSON Schema

Name	Required	Description
`location`	Yes
`timestamp`	Yes
`simulated`	Yes
`metrics`	Yes

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, indicating safe reads. The description adds value by explaining that data is simulated by default and the need to switch to a real backend in production. However, it mentions a 'simulated' parameter not present in the input schema, which could cause confusion.

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 consists of two concise sentences, front-loading the purpose and then adding behavioral notes. No unnecessary information.

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

Completeness4/5

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

Given the presence of an output schema (not shown), the description need not detail return values. It covers purpose, funnel step, simulation behavior, and production considerations. The only gap is the mention of a 'simulated' parameter not in the schema, which slightly reduces completeness.

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?

Input schema has 100% coverage with descriptions for both parameters. The tool description does not add significant semantic meaning beyond what the schema provides. Baseline is 3 per guidelines.

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 action: fetch current values, rolling averages, and thresholds for given metrics at a location. It also identifies itself as 'Step 3 of the funnel', distinguishing it from sibling tools like find_metrics (likely step 2) and analyse/diagnostic_categorize (post-processing).

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 provides context on when to use this tool ('Step 3 of the funnel'), implying it follows find_metrics. It also mentions the simulation default and production swap, guiding usage scenarios. However, it does not explicitly state when not to use it or list direct alternatives.

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.

4 tool updatesv2.0.0Jun 24, 2026
- First observedanalyse
- First observeddiagnostic_categorize
- First observedfind_metrics
- First observedget_data_metrics

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.1/5.0

Scored 2026-06-24 23:55 across 4 tools

Disambiguation5/5

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 Consistency2/5

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.

Tool Count4/5

With 4 tools, the server is appropriately scoped for a focused diagnostic pipeline. Each tool serves a clear purpose without redundancy.

Completeness4/5

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.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

mttrlyOAuth
com.mttrly
AI-powered incident management and server monitoring via MCP.
Monitoring Observability
3
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
microservices.sh
sh.microservices
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloud Platforms Agent Orchestration Developer Tools
21
pearl-api-mcp-server A
com.pearl.mcp
Hybrid human + AI expertise for faster, trusted answers and decisions via MCP Server.
Search Knowledge & Memory
42

Related MCP Servers

flyto-indexerofficial
Code Analysis Developer Tools Security
flytohub
A
license
Not graded
quality
A
maintenance
MCP server that gives AI assistants impact analysis, cross-project reference tracking, and code health scoring.
Updated a day ago (2026-09-13 19:43 UTC)
4
Apache 2.0
Wireshark MCP Server
Networking & Infrastructure Security
iflow-mcp
A
license
Not graded
quality
D
maintenance
A 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.
Updated 7 months ago (2026-02-26 08:43 UTC)
MIT
OpenShift SRE Copilot
Monitoring RAG Systems AI & Machine Learning
agentic-devops
F
license
A
quality
D
maintenance
AI-powered MCP server for enterprise OpenShift/Kubernetes cluster management, providing diagnostic tools, RAG knowledge retrieval, and autonomous remediation recommendations.
Updated 3 months ago (2026-06-14 19:43 UTC)
9
-
testing-mcp
Testing & QA Tools Developer Tools
charlieNearform
F
license
Not graded
quality
B
maintenance
MCP server that enables AI agents to programmatically run tests, query results, and receive intelligent recommendations about test execution strategy.
Updated 2 months ago (2026-07-27 15:50 UTC)
-

Branch Diagnostics MCP

The problem (why this exists)

What it does — the funnel

Architecture & design decisions

Why cURL metrics are the right signal

The MCP surface

Design decisions worth calling out

Worked example

Install & run

Simulated data — going to production

Evolution

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

flyto-indexerofficial