MCP Server Issues

Solutions for MCP server connection, transport, and tool execution problems

Overview
Connection Issues
Transport Mode Issues
Tool Execution Errors
Session Management Issues
Server-Specific Issues
Debugging MCP Servers
See Also

Overview

MCP (Model Context Protocol) issues typically fall into these categories:

Category	Symptoms	Common Causes
Connection	Server not responding	Server not started, wrong port
Transport	Protocol errors	Mismatched transport modes
Tools	Tool execution fails	Missing dependencies, bad input
Sessions	Timeout, disconnection	Long operations, resource limits

Connection Issues

Server Not Responding

Symptom:

ConnectionRefusedError: [Errno 111] Connection refused

Solutions:

Check if server is running:

# For HTTP transport
curl http://localhost:8101/
   
# Check process
ps aux | grep "MCP.*server"

Start the server manually:

# Start all servers
./start_OHMind.sh
   
# Or start individual server
python -m OHMind_agent.MCP.Chem.server --transport streamable_http --port 8101

Check port availability:

lsof -i :8101
netstat -tlnp | grep 8101

Wrong Port Configuration

Symptom: Server running but client can’t connect

Solutions:

Verify port configuration:

# Check environment variables
echo $MCP_CHEM_PORT      # Default: 8101
echo $MCP_HEMDESIGN_PORT # Default: 8102
echo $MCP_ORCA_PORT      # Default: 8103
echo $MCP_MULTIWFN_PORT  # Default: 8104
echo $MCP_GROMACS_PORT   # Default: 8105

Check mcp.json configuration:

{
  "mcpServers": {
    "OHMind-Chem": {
      "transport": "streamable_http",
      "url": "http://localhost:8101/"
    }
  }
}

Test connectivity:

for port in 8101 8102 8103 8104 8105; do
  echo -n "Port $port: "
  curl -s -o /dev/null -w "%{http_code}" "http://localhost:$port/" || echo "failed"
  echo ""
done

Server Startup Failure

Symptom:

ERROR: Failed to start MCP server: OHMind-Chem

Solutions:

Check server logs:
```
tail -f OHMind_logs/chem_mcp.log
```

Run server manually to see errors:

PYTHONPATH=. python -m OHMind_agent.MCP.Chem.server --transport stdio

Check dependencies:

python -c "from OHMind_agent.MCP.Chem.server import mcp; print('OK')"

Transport Mode Issues

stdio vs HTTP Mismatch

Symptom:

Error: Invalid transport mode

Solutions:

For stdio transport (Chainlit UI):

{
  "command": "python",
  "args": ["-m", "OHMind_agent.MCP.Chem.server", "--transport", "stdio"]
}

For HTTP transport (Backend/CLI):

{
  "transport": "streamable_http",
  "url": "http://localhost:8101/"
}

Verify server is using correct transport:

# Start with explicit transport
python -m OHMind_agent.MCP.Chem.server --transport streamable_http --port 8101

HTTP Transport Not Working

Symptom: HTTP requests fail or timeout

Solutions:

Check server is in HTTP mode:

# Server should show:
# INFO: Uvicorn running on http://0.0.0.0:8101

Test endpoint:
```
curl -v http://localhost:8101/
```

Check firewall:

sudo ufw status
# Allow port if needed
sudo ufw allow 8101

stdio Transport Hangs

Symptom: Server starts but doesn’t respond to commands

Solutions:

Check for buffering issues:

# Run with unbuffered output
PYTHONUNBUFFERED=1 python -m OHMind_agent.MCP.Chem.server --transport stdio

Verify stdin/stdout not redirected:

# Test with echo
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
  python -m OHMind_agent.MCP.Chem.server --transport stdio

Tool Execution Errors

Tool Not Found

Symptom:

ToolNotFoundError: Tool 'xyz' not found in server

Solutions:

List available tools:

from OHMind_agent.agents.mcp_session_manager import get_session_manager
   
manager = get_session_manager()
for server, tools in manager.tools_by_server.items():
    print(f"{server}:")
    for tool in tools:
        print(f"  - {tool.name}")

Check tool is registered:

# For HTTP server
curl http://localhost:8101/tools/list

Verify server has tool:

# In server code, check @mcp.tool() decorators

Tool Execution Timeout

Symptom:

TimeoutError: Tool execution exceeded timeout

Solutions:

Increase timeout in client:

# In session manager configuration
config = {
    "timeout": 300  # 5 minutes
}

Check for long-running operations:
- QM calculations can take hours
- MD simulations can take days
- Use async/background execution

Monitor tool progress:

# Check server logs
tail -f OHMind_logs/orca_mcp.log

Tool Input Validation Error

Symptom:

ValidationError: Invalid input for tool 'optimize_hem_design'

Solutions:

Check tool schema:

tool = manager.get_tools("OHMind-HEMDesign")[0]
print(tool.args_schema.schema())

Verify input format:

# Correct format
{
    "backbone": "PBF_BB_1",
    "cation_name": "piperidinium",
    "property": "multi",
    "num_part": 100,
    "steps": 20
}

Check required vs optional fields

Tool Returns Error

Symptom:

ToolError: SMILES parsing failed

Solutions:

Check input validity:

from rdkit import Chem
mol = Chem.MolFromSmiles("your_smiles")
if mol is None:
    print("Invalid SMILES")

Check server logs for details:

grep -i error OHMind_logs/chem_mcp.log | tail -20

Test tool directly:

from OHMind_agent.MCP.Chem.server import smiles_to_mol
result = smiles_to_mol("CCO")
print(result)

Session Management Issues

Session Timeout

Symptom:

SessionError: Session expired or disconnected

Solutions:

Check session manager state:

manager = get_session_manager()
print(f"Active sessions: {list(manager._active_sessions.keys())}")

Reinitialize sessions:

await cleanup_mcp_sessions()
manager = await initialize_mcp_sessions(server_configs)

Increase keep-alive settings

Multiple Session Conflicts

Symptom: Tools work sometimes but fail randomly

Solutions:

Use single global session manager:

# Don't create multiple managers
manager = get_session_manager()  # Always returns same instance

Check for concurrent access issues

Ensure proper cleanup:

# In application shutdown
await cleanup_mcp_sessions()

Memory Leak in Sessions

Symptom: Memory usage grows over time

Solutions:

Monitor memory:

ps aux | grep "MCP.*server" | awk '{print $6}'

Restart servers periodically:
```
./stop_OHMind.sh
./start_OHMind.sh
```
Check for unclosed resources in tools

Server-Specific Issues

OHMind-Chem Issues

Common problems:

RDKit not available:

python -c "from rdkit import Chem; print('OK')"

Tavily API key missing:

echo $TAVILY_API_KEY
# Set if missing
export TAVILY_API_KEY="your-key"

OHMind-HEMDesign Issues

Common problems:

VAE model not found:
```
ls -la OHMind/OHVAE/model.epoch-*
```

HEM_SAVE_PATH not writable:

mkdir -p "$HEM_SAVE_PATH"
touch "$HEM_SAVE_PATH/test" && rm "$HEM_SAVE_PATH/test"

OHMind-ORCA Issues

Common problems:

ORCA binary not found:

echo $OHMind_ORCA
ls -la "$OHMind_ORCA"

MPI not configured:

echo $OHMind_MPI
ls -la "$OHMind_MPI/mpirun"

QM_WORK_DIR issues:

mkdir -p "$QM_WORK_DIR"
chmod 755 "$QM_WORK_DIR"

OHMind-Multiwfn Issues

Common problems:

Multiwfn binary not found:

echo $MULTIWFN_PATH
ls -la "$MULTIWFN_PATH"

Missing input files:
- Multiwfn requires wavefunction files (.wfn, .wfx, .molden)
- Run QM calculation first

OHMind-GROMACS Issues

Common problems:

GROMACS not in PATH:

which gmx
# If not found, source GROMACS
source /path/to/gromacs/bin/GMXRC

MD_WORK_DIR issues:

mkdir -p "$MD_WORK_DIR"
chmod 755 "$MD_WORK_DIR"

Debugging MCP Servers

Enable Debug Logging

# Set log level
export MCP_LOG_LEVEL=DEBUG

# Or in Python
import logging
logging.getLogger("OHMind_agent.MCP").setLevel(logging.DEBUG)

Manual Server Testing

# Test Chem server
PYTHONPATH=. python -c "
from OHMind_agent.MCP.Chem.server import mcp
print('Tools:', [t.name for t in mcp.list_tools()])
"

# Test tool directly
PYTHONPATH=. python -c "
from OHMind_agent.MCP.Chem.server import get_molecular_weight
result = get_molecular_weight('CCO')
print('Result:', result)
"

MCP Protocol Debugging

# Capture MCP messages
python -m OHMind_agent.MCP.Chem.server --transport stdio 2>&1 | tee mcp_debug.log

# Send test message
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
  python -m OHMind_agent.MCP.Chem.server --transport stdio

Health Check Script

#!/bin/bash
# mcp_health_check.sh

echo "=== MCP Server Health Check ==="

servers=(
    "OHMind-Chem:8101"
    "OHMind-HEMDesign:8102"
    "OHMind-ORCA:8103"
    "OHMind-Multiwfn:8104"
    "OHMind-GROMACS:8105"
)

for server in "${servers[@]}"; do
    name="${server%%:*}"
    port="${server##*:}"
    
    echo -n "$name (port $port): "
    
    response=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:$port/" 2>/dev/null)
    
    if [ "$response" = "200" ]; then
        echo "✅ Running"
    elif [ "$response" = "000" ]; then
        echo "❌ Not responding"
    else
        echo "⚠️  HTTP $response"
    fi
done

echo ""
echo "=== Check Complete ==="

MCP Server Issues

Table of Contents

Overview

Connection Issues

Server Not Responding

Wrong Port Configuration

Server Startup Failure

Transport Mode Issues

stdio vs HTTP Mismatch

HTTP Transport Not Working

stdio Transport Hangs

Tool Execution Errors

Tool Not Found

Tool Execution Timeout

Tool Input Validation Error

Tool Returns Error

Session Management Issues

Session Timeout

Multiple Session Conflicts

Memory Leak in Sessions

Server-Specific Issues

OHMind-Chem Issues

OHMind-HEMDesign Issues

OHMind-ORCA Issues

OHMind-Multiwfn Issues

OHMind-GROMACS Issues

Debugging MCP Servers

Enable Debug Logging

Manual Server Testing

MCP Protocol Debugging

Health Check Script

See Also