Troubleshooting

Troubleshooting

Common issues and their solutions when using MCPHub.nvim.

Environment Requirements

Ensure these dependencies are installed:

node --version    # Should be >= 18.0.0
python --version  # Should be installed
uvx --version    # Should be installed

Most MCP servers use npx or uvx - verify these work in your terminal.

LLM Model Issues

If the LLM isn't making correct tool calls:

1. Schema Support

   • Models with function calling support (like claude-3.5) work best with Avante's schema format
   • Only top-tier models handle XML-based tool formats correctly
   • Consider upgrading to a better model if seeing incorrect tool usage

2. Common Tool Call Issues

   • Missing action field
   • Incorrect server_name
   • Missing tool_name or uri
   • Malformed arguments

3. Recommended Models

   • GPT-4o
   • Claude 3.5 Sonnet
   • Claude 3.7
   • Gemini 2.0 Flash
   • Gemini 2.0 Pro
   • Mistral Large

Port Issues

If you get EADDRINUSE error when starting MCPHub:

1. Find the process using the port:

   lsof -i :[port]  # Find process ID

2. Kill the process:

   kill [pid]  # Kill the process

Alternatively, change the port in your config:

require("mcphub").setup({
    port = 37374  -- Use different port
})

Configuration File

Common configuration issues:

1. Invalid Path

   • Ensure config path is absolute
   • Default: ~/.config/mcphub/servers.json

2. Invalid JSON

   • Verify file contains valid JSON
   • Must have mcpServers key
   • Check JSON syntax

3. Server Configuration

   • Validate server-specific requirements
   • Check command and args exist on system
   • Verify environment variables

MCP Server Issues

Validate server setup using:

1. MCP Inspector

   • GUI tool for verifying server operation
   • Tests server endpoints
   • Validates capabilities

2. mcp-cli

   • Command-line tool for testing
   • Works with config files
   • Quick server validation

3. MCPHub UI

   • Check Logs view (press L)
   • Test tools individually
   • Verify resource access

Quick Test

Test minimal setup using minimal.lua.

Getting Help

1. Issue Tracker

   • Report bugs on GitHub Issues
   • Include error messages
   • Share minimal config

2. Discussions

   • Ask questions in GitHub Discussions
   • Share setups and tips
   • Request features

3. Express API

   • Access directly: http://localhost:[port]/api
   • Test server endpoints
   • Debug connection issues

Common Issues

1. Server Won't Start

   • Check node version
   • Verify mcp-hub installation
   • Check port availability

2. Tools Not Working

   • Verify server is enabled
   • Check tool isn't disabled
   • Review server logs

3. Resource Access Fails

   • Check URI format
   • Verify resource exists
   • Check server connectivity

4. Chat Plugin Issues

   • Verify extension config
   • Check tool approval settings
   • Review plugin logs