Skip to main content
Glama
rmschn

MCP Simple Example

by rmschn
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

MCP Simple Example

A Model Context Protocol (MCP) server that provides network diagnostic tools (ping, traceroute) as AI-accessible tools. Works with any MCP-compatible client

Overview

This project creates an MCP server that exposes network diagnostic commands as tools that can be called by any MCP-compatible AI assistant. The AI assistant (powered by Ollama with llama3.1:8b) can use these tools to diagnose network issues, check host connectivity, trace network paths

What is MCP?

The Model Context Protocol (MCP) is an open standard developed by Anthropic for connecting AI assistants to external tools and data sources. Instead of hardcoding tool implementations in every AI client, MCP allows:

  • Standardized Tool Interface: Tools are defined once and work with any MCP client

  • Secure Execution: Tools run in isolation, reducing security risks

  • Easy Integration: MCP clients can discover and use tools dynamically

  • Language Agnostic: Servers can be written in any language (Python, TypeScript, Go, etc.)

Components

  1. mcp_server.py: The main MCP server implementation

    • Implements the MCP protocol over stdio

    • Defines two tools: network-ping, network-traceroute

    • Handles tool execution and response formatting

  2. mcp_client.py: Interactive CLI test client

    • Allows manual testing of all tools

    • Useful for debugging without an AI assistant

Tool Definitions

Tool

Purpose

Key Parameters

network-ping

Test host reachability and latency

host, count

network-traceroute

Trace network path to host

host, max_hops, timeout

Related MCP server: netops-mcp

Prerequisites

System Requirements

Required System Tools

The server uses the following system commands (must be installed on your system):

Command

Purpose

Install (Debian/Ubuntu)

Install (macOS)

ping

ICMP echo requests

apt install iputils-ping

Built-in

traceroute

Network path tracing

apt install traceroute

Built-in

Ollama Setup (for AI Integration)

To use with an AI assistant:

  1. Install Ollama: https://ollama.ai

  2. Pull the model: ollama pull llama3.1:8b

  3. Start Ollama: ollama serve

Installation

Step 1: Clone or Navigate to the Project

cd /path/to/simple_mcp_example

Step 2: Install Dependencies with uv

# Install all dependencies using uv
uv sync

# Or install the MCP package directly
uv add mcp python-dotenv

Step 3: Verify Installation

# Check that uv created the virtual environment
ls -la .venv

# Verify Python can see the packages
uv run python -c "import mcp; print('MCP installed')"

Step 4: Install System Tools (if needed)

# Debian/Ubuntu
sudo apt update
sudo apt install iputils-ping traceroute

Usage

Direct Server Execution

Start the server directly (outputs to stderr):

uv run python mcp_server.py

Interactive Test Client

The easiest way to test the server:

# Run the interactive test client
uv run python mcp_client.py

You can then type commands like:

> ping google.com
> traceroute cloudflare.com
> quit

Configuration

Environment Variables

The server doesn't require environment variables, but you can add them to pyproject.toml if needed:

[tool.mcp-server.env]
# DEBUG=true

Customizing Tool Behavior

Edit mcp_server.py to customize:

Add New Tools

Add new Tool definitions and handlers in mcp_server.py.

API Reference

Tool: network-ping

Test connectivity and measure latency to a host.

Parameters:

Name

Type

Required

Default

Description

host

string

Yes

-

Hostname or IP address

count

integer

No

4

Number of packets

Example Request:

{
  "method": "tools/call",
  "params": {
    "name": "network-ping",
    "arguments": {
      "host": "google.com",
      "count": 4
    }
  }
}

Example Response:

# Ping Results for google.com

## Command Output
PING google.com (142.250.80.46): 56 data bytes
64 bytes from 142.250.80.46: icmp_seq=0 ttl=117 time=10.123 ms
64 bytes from 142.250.80.46: icmp_seq=1 ttl=117 time=10.456 ms
...

## Summary
✓ 0% packet loss - Host is fully reachable
Latency (RTT): min=10.1ms, avg=10.3ms, max=10.5ms

Tool: network-traceroute

Trace the network path to a destination host.

Parameters:

Name

Type

Required

Default

Description

host

string

Yes

-

Hostname or IP address

max_hops

integer

No

30

Maximum hops to trace

timeout

integer

No

5

Seconds to wait per hop

Example Request:

{
  "method": "tools/call",
  "params": {
    "name": "network-traceroute",
    "arguments": {
      "host": "cloudflare.com",
      "max_hops": 15
    }
  }
}

Troubleshooting

"ping command not found"

Solution: Install ping utilities

# Debian/Ubuntu
sudo apt install iputils-ping

# macOS
# ping is built-in

"Server timed out" or "Connection failed"

Possible causes:

  1. Server is taking too long to start

  2. Network issues between client and server

  3. Host is unreachable

Solutions:

# Check server starts correctly
uv run python mcp_server.py

License

MIT License - Feel free to use, modify, and distribute.

Available Tools

2 tools
network-pingA

Send ICMP echo requests to a host to test connectivity and measure latency.

USE CASES:
- Check if a host is reachable over the network
- Measure round-trip time (latency) to a host
- Diagnose network connectivity issues
- Verify if a firewall is blocking ICMP traffic

WHAT IT DOES:
- Sends multiple ICMP echo request packets to the target host
- Waits for echo response packets
- Reports packet loss percentage and response times

PARAMETERS:
- host: Required. The hostname or IP address to ping (e.g., 'google.com', '8.8.8.8')
- count: Optional. Number of ping packets to send (default: 4)

OUTPUT:
- Packet loss statistics
- Min/Avg/Max response times
- Will show '100% packet loss' if host is unreachable or blocking ICMP
ParametersJSON Schema
NameRequiredDescriptionDefault
hostYesThe hostname or IP address to ping (e.g., 'google.com' or '192.168.1.1')
countNoNumber of ping packets to send (default: 4)

TDQS

A4/5.0
Behavior4/5

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

With no annotations provided, the description carries the full behavioral disclosure burden. It discloses the mechanics (sends multiple ICMP echo requests, waits for responses), the metrices (packet loss, response times), and the failure behavior ('100% packet loss' when unreachable). While it does not explicitly state that this is a non-destructive read-only operation, the described behavior makes that clear, and no contradictions exist.

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

Conciseness4/5

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

The description is well-organized into USE CASES, WHAT IT DOES, PARAMETERS, and OUTPUT, making it easy to parse quickly. It is mostly concise but has some redundancy, such as the opening sentence and WHT IT DOES both stating that it sends ICMP echo requests.

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 low complexity, complete schema, and lack of an output schema, the description covers all necessary ground: purpose, use cases, behavior, parameter explanations, and output format including failure scenario. An agent has enough information to select and invoke the tool 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?

Schema description coverage is 100%, so the schema already fully documents both host and count. The description's PARAMETERS section largely repeats the schema content, adding example values but no additional meaning beyond what the schema already provides. Therefore, the baseline of 3 is appropriate.

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

Purpose4/5

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

The description opens with a specific verb and resource: 'Send ICMP echo requests to a host to test connectivity and measure latency.' This clearly defines the tool's core function. However, it does noot explicitly distinguish itself from the sibling tool network-traceroute, so it misses the full 5 for sibling differentiation.

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 USE CASES section provides explicit scenarios such as 'Check if a host is reachable' and 'Diagnose network connectivity issues,' giving clear context for when to use the tool. It does not mention when not to use it or point to network-traceroute as the alternative for route-path diagnistics, so it stops short of a 5.

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

network-tracerouteA

Trace the route that packets take to reach a destination host.

USE CASES:
- Identify network path between source and destination
- Diagnose where network latency is occurring
- Find broken or slow network hops
- Understand network topology for debugging

WHAT IT DOES:
- Sends packets with increasing TTL (Time To Live) values
- Each router along the path decrements TTL and returns its IP
- Shows all intermediate hops between your machine and target

PARAMETERS:
- host: Required. The hostname or IP address to trace (e.g., 'cloudflare.com')
- max_hops: Optional. Maximum number of hops to trace (default: 30)
- timeout: Optional. Seconds to wait for each hop response (default: 5)

OUTPUT:
- List of all hops (routers) along the path
- IP address of each hop
- Round-trip time for each hop
- Shows '* * *' for hops that don't respond

NOTE: On Windows, this command is called 'tracert' instead of 'traceroute'
ParametersJSON Schema
NameRequiredDescriptionDefault
hostYesThe hostname or IP address to trace route to (e.g., 'example.com')
timeoutNoSeconds to wait for each hop response (default: 5)
max_hopsNoMaximum number of hops to trace (default: 30)

TDQS

A4.3/5.0
Behavior4/5

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

No annotations are present, so the description carries the full burden. It transparently explains the TTL mechanism, describes that each router returns its IP, and discloses that unresponsive hops appear as '* * *'. It does not mention potential privilege requirements or firewall interference, but the core behavior is well covered.

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 well-structured: a front-loaded purpose sentence, followed by USE CASES, WHAT IT DOES, PARAMETERS, OUTPUT, and a platform-specific NOTE. Each section adds distinct value, and there is no filler or redundancy.

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 there is no output schema or annotations, the description fully covers what an agent needs: required and optional parameters with defaults, the output shape (hops, IPs, round-trip times, '* * *'), and the Windows 'tracert' naming difference. This is complete for a network diagnostic tool of comparable complexity.

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 already documents all three parameters with descriptions, defaults, and ranges, achieving 100% coverage. The PARAMETERS section largely restates this structured information, adding only a 'Required' label and an example host—marginal added meaning beyond the schema.

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 opening sentence uses a specific verb-resource pairing ('Trace the route...') and the USE CASES and WHAT IT DOES sections make clear this is a network path/hop discovery tool. It is easily distinguished from the sibling network-ping by its focus on intermediate hops rather than simple reachability.

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 clear contexts for use ('Identify network path', 'Diagnose where network latency is occurring', 'Find broken or slow network hops', 'Understand network topology for debugging'). However, it does not explicitly contrast with network-ping or state when not to use this tool, so it falls short of full alternative routing.

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. 2 tool updatesv0.1.0
    • First observednetwork-ping
    • First observednetwork-traceroute
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.2/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: ping tests reachability and latency, while traceroute maps the network path. There is no realistic confusion between them.

Naming Consistency5/5

Both tools follow the same network-<command> naming pattern, making the set predictable and easy to navigate. The consistency holds across both tools.

Tool Count3/5

With only two tools, the server feels thin, but the pair of ping and traceroute forms a natural, coherent unit for basic network diagnostics. It is slightly under the typical well-scoped range but not unreasonable for a simple example server.

Completeness4/5

For basic network troubleshooting, ping and traceroute cover the two most common diagnostic needs: connectivity/latency and route/path analysis. A DNS lookup or port check would be a minor enhancement, but the current surface is not severely incomplete for the implied scope.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Keel

    seayniclabs
    A
    license
    A
    quality
    C
    maintenance
    Network diagnostics — ping, traceroute, DNS lookup, port scanning, and connectivity testing via MCP.
    14
    MIT

  • netops-mcp

    alpadalar
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides network operations tools such as ping, traceroute, DNS queries, and nmap scans via MCP, enabling network diagnostics and monitoring through natural language.
    14
    MIT

  • NetPulse

    hind77
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that exposes live network monitoring data as Resources and diagnostic capabilities as Tools, letting AI assistants query network health conversationally.
    6
    MIT