# MCP Tester

> Test MCP server connectivity and tool execution. Use when adding new MCP servers, debugging tool integration, or verifying tool availability. Supports stdio, http, and sse server types. Use when this capability is needed.

- Skill: `tomevault-io/mcp-tester-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/mcp-tester-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/mcp-tester-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/mcp-tester-2

---


# MCP Server Testing

Test and debug MCP (Model Context Protocol) server connections.

## Server Types

| Type | Transport | Use Case |
|------|-----------|----------|
| `stdio` | Standard I/O | Local processes, CLI tools |
| `http` | HTTP/HTTPS | Remote APIs, cloud services |
| `sse` | Server-Sent Events | Streaming endpoints |

## Test Categories

### 1. Connection Test

Verify server is reachable and initializes correctly.

```bash
# Test stdio server
npx -y @modelcontextprotocol/inspector stdio -- npx -y @modelcontextprotocol/server-filesystem /tmp

# Test HTTP server
curl -X POST https://mcp.service.com/initialize \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'
```

### 2. Tool Discovery

List available tools from a connected server.

```bash
# Using MCP inspector
npx -y @modelcontextprotocol/inspector stdio -- python ./mcp_servers/my_server.py

# Check tool listing
curl -X POST https://mcp.service.com/tools/list \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'
```

### 3. Tool Execution

Test individual tool invocation.

```python
# Python test script
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def test_tool():
    server_params = StdioServerParameters(
        command="npx",
        args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List tools
            tools = await session.list_tools()
            print(f"Available tools: {[t.name for t in tools.tools]}")

            # Execute tool
            result = await session.call_tool(
                "read_file",
                {"path": "/tmp/test.txt"}
            )
            print(f"Result: {result.content}")

asyncio.run(test_tool())
```

### 4. Error Handling

Verify graceful error handling.

```python
# Test invalid tool call
try:
    result = await session.call_tool("nonexistent_tool", {})
except Exception as e:
    print(f"Expected error: {e}")

# Test invalid parameters
try:
    result = await session.call_tool("read_file", {"invalid": "param"})
except Exception as e:
    print(f"Expected error: {e}")
```

## Configuration Validation

### .mcp.json Schema

```json
{
  "mcpServers": {
    "server-name": {
      "type": "stdio | http | sse",
      "command": "string (for stdio)",
      "args": ["array", "of", "args"],
      "env": {
        "VAR": "value or ${ENV_VAR}"
      },
      "url": "string (for http/sse)",
      "headers": {
        "Authorization": "Bearer ${TOKEN}"
      }
    }
  }
}
```

### Environment Variable Expansion

```json
{
  "env": {
    "API_KEY": "${MY_API_KEY}",
    "BASE_URL": "${BASE_URL:-http://localhost:8080}"
  }
}
```

## Debugging Commands

```bash
# Check if server process starts
npx -y @modelcontextprotocol/server-filesystem /tmp

# Verbose mode for debugging
DEBUG=mcp:* npx -y @modelcontextprotocol/inspector stdio -- ./my_server

# Check environment variables
env | grep -E 'API_KEY|TOKEN|URL'

# Test HTTP endpoint
curl -v https://mcp.service.com/health
```

## Common Issues

| Issue | Cause | Solution |
|-------|-------|----------|
| Connection refused | Server not running | Start server process |
| Tool not found | Wrong tool name | Check `tools/list` response |
| Auth error | Missing/invalid token | Set environment variable |
| Timeout | Server slow/hanging | Check server logs |
| Parse error | Invalid JSON-RPC | Validate request format |

## Health Check Endpoint

```python
@app.get("/health")
async def health_check():
    """MCP server health check."""
    return {"status": "healthy", "version": "1.0.0"}
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/rwxproject) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->