VPP MCP Server (Go Implementation)

A Model Context Protocol (MCP) server written in Go for debugging Vector Packet Processing (VPP) instances running in Kubernetes pods or as standalone daemons.

Overview

This MCP server provides tools to interact with VPP instances for debugging purposes. It supports dual execution modes: Kubernetes (CalicoVPP pods) and Standalone (local VPP daemon). It exposes VPP functionality through MCP tools that can be used by AI agents and other MCP clients.

Features

• Dual Execution Modes:
  • Kubernetes: Executes VPP commands on Kubernetes pods running CalicoVPP
  • Standalone: Executes VPP commands on a local VPP daemon via vppctl socket
• Multiple Transport Modes:
  • Stdio for local client-server communication
  • HTTP/SSE for remote network access between machines
• 44 Debugging Tools: Comprehensive toolset for VPP and BGP debugging
  • Pod management (list all CalicoVPP pods)
  • Version information
  • Interface statistics and addresses
  • Error counters and error clearing
  • Session information and statistics
  • TCP statistics
  • NPOL rules and policies
  • CNAT translations and sessions
  • Runtime statistics
  • IP routing tables and FIBs
  • Tunnel interface information
  • VPP logs
  • Packet trace, PCAP, and dispatch trace capture
  • Capture cleanup and lock management
  • BGP neighbors and global information
  • BGP RIB queries (IPv4/IPv6, IPs, prefixes)
  • Container log retrieval (agent and vpp-manager)
• Official MCP Go SDK: Uses the official Model Context Protocol Go SDK maintained by Google
• Go Implementation: Fast, efficient, and easy to deploy
• Extensible Architecture: Easy to add more VPP debugging tools
• Remote Access: Connect from any machine to debug VPP instances on remote servers

Prerequisites

• Go 1.24+
• Kubernetes mode: kubectl installed and configured with access to your Kubernetes cluster; VPP running in Kubernetes pods (e.g., Calico VPP dataplane)
• Standalone mode: VPP running as a local daemon with vppctl accessible (default socket: /var/run/vpp/cli.sock)
• MCP client (like Claude Desktop, Cline, or other MCP-compatible tools)

Installation

1. Clone or navigate to the project directory:

cd /home/aritrbas/vpp/vpp-mcp

2. Download Go dependencies:

go mod tidy

3. Build the server:

go build -o vpp-mcp-server main.go

Usage

Running the MCP Server

The server supports two transport modes: stdio (local) and http (network).

Stdio Transport (Local)

Start the server using stdio transport (default):

./vpp-mcp-server

Or with explicit flag:

./vpp-mcp-server --transport=stdio

Or run directly with Go:

go run main.go

HTTP Transport (Network)

Start the server with HTTP transport for remote access:

./vpp-mcp-server --transport=http --port=8080

This exposes the following endpoints:

• http://localhost:8080/sse - MCP SSE endpoint for client connections
• http://localhost:8080/health - Health check endpoint
• http://localhost:8080/ - Server information page

For remote access, replace localhost with the server's IP address or hostname.

Available Tools

Note: In Kubernetes mode, VPP tools use namespace calico-vpp-dataplane and container vpp. In standalone mode, tools connect via the VPP socket.

Common Parameters for VPP Tools:

• pod_name: (Kubernetes mode, required) Name of the Kubernetes pod running VPP
• mode: (optional) "kubernetes" (default) or "standalone"
• sock_path: (Standalone mode, optional) VPP socket path (default: /var/run/vpp/cli.sock)

vpp_show_version

• Description: Get VPP version information
• Command: vppctl show version

vpp_show_int

• Description: Get VPP interface information
• Command: vppctl show int

vpp_show_int_addr

• Description: Get VPP interface address information
• Command: vppctl show int addr

vpp_show_hardware_interfaces

• Description: Shows detailed hardware interface information with VIRTIO queue statistics for all interfaces
• Command: vppctl show hardware-interfaces
• Parameters:
  • pod_name (required): Name of the Kubernetes pod running VPP
• Output: Provides comprehensive hardware-level details including:
  • Hardware interface names and indices
  • Link state and speed
  • MAC addresses
  • Driver information
  • VIRTIO queue statistics and depths
  • Hardware offload capabilities

vpp_show_errors

• Description: Get VPP error counters
• Command: vppctl show errors

vpp_show_session_verbose

• Description: Get VPP session information with verbose output
• Command: vppctl show session verbose 2

vpp_show_npol_rules

• Description: List rules that are referenced by policies
• Command: vppctl show npol rules

vpp_show_npol_policies

• Description: List all the policies that are referenced on interfaces
• Command: vppctl show npol policies

vpp_show_npol_ipset

• Description: List ipsets that are referenced by rules (IPsets are just list of IPs)
• Command: vppctl show npol ipset

vpp_show_npol_interfaces

• Description: Show the resulting policies configured for every interface in VPP. The first IPv4 address of every pod is provided to help identify which pod and interface belongs to.
• Command: vppctl show npol interfaces
• Output interpretation:
  • tx: contains rules that are applied on packets that LEAVE VPP on a given interface. Rules are applied top to bottom.
  • rx: contains rules that are applied on packets that ENTER VPP on a given interface. Rules are applied top to bottom.
  • profiles: are specific rules that are enforced when a matched rule action is PASS or when no policies are configured.

vpp_trace

• Description: Capture VPP packet traces (mutating - modifies VPP trace state)
• Command: vppctl trace add
• Additional Parameters:
  • count (optional): Number of packets to capture (default: 500)
  • timeout (optional): Capture duration in seconds (default: 30)
  • interface (optional): Interface type - phy|af_xdp|af_packet|avf|vmxnet3|virtio|rdma|dpdk|memif|vcl (default: virtio)

vpp_pcap

• Description: Capture VPP packets to pcap file (mutating - writes capture files)
• Command: vppctl pcap trace
• Additional Parameters:
  • count (optional): Number of packets to capture (default: 500)
  • timeout (optional): Capture duration in seconds (default: 30)
  • interface (optional): Interface name (e.g., host-eth0) or 'any' (default: 'any')

vpp_dispatch

• Description: Capture VPP dispatch trace to pcap file (mutating - writes capture files)
• Command: vppctl pcap dispatch trace
• Additional Parameters:
  • count (optional): Number of packets to capture (default: 500)
  • timeout (optional): Capture duration in seconds (default: 30)
  • interface (optional): Interface type - phy|af_xdp|af_packet|avf|vmxnet3|virtio|rdma|dpdk|memif|vcl (default: virtio)

vpp_capture_cleanup

• Description: Force cleanup of all VPP capture operations (trace, pcap, dispatch) (mutating)
• Command: Stops all captures, removes lock files, cleans up temporary capture files
• Use when: A previous capture operation failed or left stale locks

vpp_get_pods

• Description: List all CalicoVPP pods with their IPs and nodes on which they are running
• Command: kubectl get pods -n calico-vpp-dataplane -owide
• Parameters: None required

vpp_clear_errors

• Description: Reset the error counters (mutating)
• Command: vppctl clear errors

vpp_tcp_stats

• Description: Display global statistics reported by TCP
• Command: vppctl show tcp stats

vpp_session_stats

• Description: Display global statistics reported by the session layer
• Command: vppctl show session stats

vpp_get_logs

• Description: Display VPP logs
• Command: vppctl show logging

vpp_show_cnat_translation

• Description: Shows the active CNAT translations
• Command: vppctl show cnat translation

vpp_show_cnat_session

• Description: Lists the active CNAT sessions from the established five tuple to the five tuple rewrites
• Command: vppctl show cnat session
• Output interpretation: The output shows the incoming 5-tuple first that is used to match packets along with the protocol. Then it displays the 5-tuple after dNAT & sNAT, followed by the direction and finally the age in seconds. direction being input for the PRE-ROUTING sessions and output is the POST-ROUTING sessions

vpp_clear_run

• Description: Clears live running error stats in VPP (mutating)
• Command: vppctl clear run

vpp_show_run

• Description: Shows live running error stats in VPP
• Command: vppctl show run
• Debugging workflow: Sometimes to debug an issue, you might need to run vpp_clear_run to erase historic stats and then wait for a few seconds in the issue state / run some tests so that the error stats are repopulated and then run vpp_show_run in order to diagnose what is going on in the system
• Output interpretation: A loaded VPP will typically have (1) a high Vectors/Call maxing out at 256 (2) a low loops/sec struggling around 10000. The Clocks column tells you the consumption in cycles per node on average. Beyond 1e3 is expensive.

vpp_show_tun_all

• Description: Display all tunnel interfaces in VPP
• Command: vppctl show tun
• Parameters:
  • pod_name (required): Name of the Kubernetes pod running VPP
• Output: Shows detailed information about all tunnel interfaces configured in VPP, including:
  • Tunnel interface names and indices
  • Tunnel types (GRE, VXLAN, IPSec, etc.)
  • Source and destination addresses
  • Tunnel state and configuration

vpp_show_tun_interface

• Description: Inspect a specific tunnel interface in VPP by running vppctl show tun and filtering to the requested interface (emulating grep <name> -A 40)
• Command: vppctl show tun | grep <interface_name> -A 40 (emulated)
• Parameters:
  • pod_name (required): Name of the Kubernetes pod running VPP
  • interface_name (required): The tunnel interface to inspect (for example, tun1)
• Output: Provides detailed statistics for the selected tunnel interface, including queue depths, buffer usage, and offload capabilities

vpp_show_ip_table

• Description: Prints all available IPv4 VRFs
• Command: vppctl show ip table

vpp_show_ip6_table

• Description: Prints all available IPv6 VRFs
• Command: vppctl show ip6 table

vpp_show_ip_fib

• Description: Prints all routes in a given pod IPv4 VRF
• Command: vppctl show ip fib index <idx>
• Additional Parameters:
  • fib_index (required): The FIB table index

vpp_show_ip6_fib

• Description: Prints all routes in a given pod IPv6 VRF
• Command: vppctl show ip6 fib index <idx>
• Additional Parameters:
  • fib_index (required): The FIB table index

vpp_show_ip_fib_prefix

• Description: Prints information about a specific prefix in a given pod IPv4 VRF
• Command: vppctl show ip fib index <idx> <prefix>
• Additional Parameters:
  • fib_index (required): The FIB table index
  • prefix (required): The IP prefix to query (e.g., 10.0.0.0/24)

vpp_show_ip6_fib_prefix

• Description: Prints information about a specific prefix in a given pod IPv6 VRF
• Command: vppctl show ip6 fib index <idx> <prefix>
• Additional Parameters:
  • fib_index (required): The FIB table index
  • prefix (required): The IPv6 prefix to query (e.g., 2001:db8::/32)

bgp_show_neighbors

• Description: Show BGP peers (Kubernetes/CalicoVPP only)
• Command: gobgp neighbor
• Parameters:
  • pod_name (required): Name of the Kubernetes pod running the agent container with gobgp

bgp_show_global_info

• Description: Show BGP global information
• Command: gobgp global
• Parameters:
  • pod_name (required): Name of the Kubernetes pod running the agent container with gobgp

bgp_show_global_rib4

• Description: Show BGP IPv4 RIB information
• Command: gobgp global rib -a 4
• Parameters:
  • pod_name (required): Name of the Kubernetes pod running the agent container with gobgp

bgp_show_global_rib6

• Description: Show BGP IPv6 RIB information
• Command: gobgp global rib -a 6
• Parameters:
  • pod_name (required): Name of the Kubernetes pod running the agent container with gobgp

bgp_show_ip

• Description: Show BGP RIB entry for a specific IP
• Command: gobgp global rib <ip>
• Parameters:
  • pod_name (required): Name of the Kubernetes pod running the agent container with gobgp
  • parameter (required): The IP address to query

bgp_show_prefix

• Description: Show BGP RIB entry for a specific prefix
• Command: gobgp global rib <prefix>
• Parameters:
  • pod_name (required): Name of the Kubernetes pod running the agent container with gobgp
  • parameter (required): The prefix to query (e.g., 10.0.0.0/24)

bgp_show_neighbor

• Description: Show detailed information for a specific BGP neighbor
• Command: gobgp neighbor <neighborIP>
• Parameters:
  • pod_name (required): Name of the Kubernetes pod running the agent container with gobgp
  • parameter (required): The neighbor IP address to query

get_agent_logs

• Description: Fetch recent logs from the CalicoVPP agent container for a pod
• Command: kubectl logs -n calico-vpp-dataplane <pod> -c agent --tail <tail_lines>
• Parameters:
  • pod_name (required): Name of the Kubernetes pod
  • tail_lines (optional): Number of recent lines to fetch (default: 200, max: 5000)

get_vpp_manager_logs

• Description: Fetch recent logs from the CalicoVPP vpp container (vpp-manager daemon) for a pod
• Command: kubectl logs -n calico-vpp-dataplane <pod> -c vpp --tail <tail_lines>
• Parameters:
  • pod_name (required): Name of the Kubernetes pod
  • tail_lines (optional): Number of recent lines to fetch (default: 200, max: 5000)

CalicoVPP BGP Troubleshooting Workflow

This workflow mirrors the upstream troubleshooting guide and is adapted to this MCP server's toolset:

• Upstream reference: https://github.com/projectcalico/vpp-dataplane/blob/master/docs/bgp/troubleshooting.md
• Local runbook: skills/BGP_TROUBLESHOOTING_WORKFLOW.md

Kubernetes Pod Management

The server executes VPP commands on existing Kubernetes pods:

1. Connects to specified pods via kubectl
2. Executes vppctl commands in the VPP container
3. Executes gobgp commands in the agent container
4. Returns results via MCP protocol

Configuration

MCP Client Configuration

Local Configuration (Stdio Transport)

To use this server with an MCP client on the same machine, add it to your client's configuration. For example, with Claude Desktop, add to your claude_desktop_config.json:

{
  "mcpServers": {
    "vpp-debug": {
      "command": "/home/aritrbas/vpp/vpp-mcp/vpp-mcp-server",
      "cwd": "/home/aritrbas/vpp/vpp-mcp"
    }
  }
}

Remote Configuration (HTTP Transport)

For remote access from Machine Y to Machine X:

On Machine X (Server):

1. Start the server with HTTP transport:

./vpp-mcp-server --transport=http --port=8080

2. Ensure the port is accessible (check firewall rules):

# Example: Allow port 8080 on Ubuntu/Debian
sudo ufw allow 8080/tcp

On Machine Y (Client): Configure your MCP client to connect to the HTTP endpoint. For example, with Claude Desktop:

{
  "mcpServers": {
    "vpp-debug-remote": {
      "url": "http://<machine-x-ip>:8080/sse",
      "transport": "sse"
    }
  }
}

Replace <machine-x-ip> with the actual IP address or hostname of Machine X.

Security Considerations:

• The HTTP transport does not include authentication by default
• For production use, consider adding:
  • Reverse proxy with TLS (nginx, Apache)
  • API authentication (API keys, OAuth)
  • Network security (VPN, SSH tunneling)
  • Firewall rules to restrict access

Example with SSH Tunnel (Secure Alternative):

# On Machine Y, create SSH tunnel
ssh -L 8080:localhost:8080 user@machine-x

# Then configure client to use localhost:8080

Customizing Default Settings

You can modify the constants in main.go to:

• Change default namespace
• Change default container name
• Add additional VPP commands as tools

Development

Project Structure

vpp-mcp/
├── main.go                      # Main MCP server implementation
├── go.mod                       # Go module definition
├── go.sum                       # Go module checksums
├── Makefile                     # Build automation
├── README.md                    # This file
├── .gitignore                   # Git ignore rules
├── vpp-mcp-server               # Compiled binary
├── docs/                        # Documentation
│   ├── QUICK_START.md          # Quick reference
│   ├── REMOTE_ACCESS.md        # Remote access guide
│   └── TEST_SUMMARY.md         # Test results
├── skills/                      # LLM workflow skills
│   └── bgp-troubleshoot.md      # BGP triage runbook
│   └── cluster-healthcheck.md   # Cluster health check
├── tests/                       # Test scripts
│   ├── test_mcp_server.sh      # Test MCP server setup in stdio transport
│   ├── demo_test.sh            # Demo all tools
│   ├── test_tool.sh            # Test individual tools
│   └── test_http_server.sh     # Test MCP server setup in HTTP transport
└── examples/                    # Example files
    └── example_mcp_requests.json # JSON-RPC examples

Building

Build the server:

go build -o vpp-mcp-server main.go

Build for different platforms:

# Linux
GOOS=linux GOARCH=amd64 go build -o vpp-mcp-server-linux main.go

# macOS
GOOS=darwin GOARCH=amd64 go build -o vpp-mcp-server-macos main.go

# Windows
GOOS=windows GOARCH=amd64 go build -o vpp-mcp-server.exe main.go

Adding New Tools

To add new VPP debugging tools:

1. Define your tool input structure:

type YourToolInput struct {
    Parameter string `json:"parameter"`
}

2. Create a tool handler function:

func (s *VPPMCPServer) handleYourTool(ctx context.Context, req *mcp.CallToolRequest, input YourToolInput) (*mcp.CallToolResult, any, error) {
    genericInput := VPPCommandInput{
        PodName:       input.PodName,
        Namespace:     input.Namespace,
        ContainerName: input.ContainerName,
    }

    return s.handleVPPCommand(ctx, genericInput, "your vppctl subcommand", "Your tool description")
}

3. Add the tool to the server in main():

tool := &mcp.Tool{
    Name:        "your_tool_name",
    Description: "Tool description",
}
mcp.AddTool(vppServer.server, tool, vppServer.handleYourTool)

Testing

1. Test server functionality:

# stdio transport
./tests/test_mcp_server.sh
# HTTP transport
./tests/test_http_server.sh

2. Demo all tools:

./tests/demo_test.sh <pod-name>

3. Test individual tool:

./tests/test_tool.sh <pod-name> vpp_show_int

Dependencies

This project uses:

• github.com/modelcontextprotocol/go-sdk - Official Model Context Protocol Go SDK maintained in collaboration with Google
• Standard Go libraries for command execution
• k8s.io/client-go - Kubernetes client library for pod discovery and ConfigMap access

Troubleshooting

Common Issues

1. kubectl access fails:

   • Verify kubectl is installed and configured
   • Check you have access to the VPP namespace
   • Ensure proper RBAC permissions for pod exec

2. vppctl commands fail:

   • Verify VPP is running in the target pod
   • Check if the pod name is correct

3. MCP connection issues:

   • Verify the binary is built correctly (go build)
   • Check MCP client configuration
   • Review server logs for errors

4. Build issues:

   • Ensure Go 1.24+ is installed
   • Run make deps to download dependencies
   • Check for any compilation errors

Logs

The server logs important events to help with debugging:

• Container lifecycle events
• Command execution results
• Error conditions

View logs by running the server and monitoring stdout/stderr output.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Future Enhancements

Planned features:

• More VPP debugging tools
• Configuration management tools
• Log analysis capabilities
• Performance monitoring tools
• Configuration file support
• Workflow support
• Workflow visualization tools
• Automated workflow execution engine