MCP Troubleshooting
Troubleshooting the Model Context Protocol (MCP) involves diagnosing issues with the external server, the network connection, or the configuration within ChatFrame.
1. Connection Refused
Symptom: ChatFrame reports a "Connection Refused" error when attempting to connect to the MCP server.
Potential Causes and Solutions:
| Cause | Solution |
|---|---|
| Server Not Running | Ensure the MCP server application is actively running on your machine or network. |
| Incorrect Port/Address | Double-check the IP address and port number configured in ChatFrame's MCP settings against the server's actual listening address. |
| Firewall Block | Your operating system's firewall may be blocking the connection. Temporarily disable the firewall or create an exception for the port. |
| Wrong Protocol | Ensure the server is communicating using the correct protocol (JSON-RPC 2.0 over HTTP/WebSockets). |
2. Tools Not Appearing
Symptom: The MCP server is connected, but the LLM is not using the tools, or the tools list is empty.
Potential Causes and Solutions:
| Cause | Solution |
|---|---|
| Server Tool Definition Error | The MCP server's tool definition (schema) may be malformed or incorrect. Check the server's logs for errors during startup. |
| LLM Selection | Ensure you have selected a model that supports tool-calling (function calling) and that the MCP server is active for the current chat session. |
| Prompt Ambiguity | The LLM may not recognize that the tool is relevant to your prompt. Try a more explicit prompt, such as, "Use the query_database tool to find..." |
3. Runtime Dependency Issues
Symptom: The MCP server fails to start or crashes immediately.
Potential Causes and Solutions:
| Cause | Solution |
|---|---|
| Missing Runtime | The server requires a runtime (e.g., Node.js, Python) that is not installed or not in your system's PATH. Install the required runtime. |
| Version Mismatch | The server may require a specific version of the runtime or a library. Check the server's documentation for version requirements. |
- Model Context Protocol. Specification. https://modelcontextprotocol.io/specification/2025-03-26
- ChatFrame. Official Website. https://www.chatframe.co/