MCP Troubleshooting & Best Practices

This document summarizes common troubleshooting methods, security and performance recommendations during use, and provides external reference resources for MCP servers.

Troubleshooting

1. Always connecting / Unable to connect

• Check configuration:
  • stdio: Is command executable? Does it need to be placed in args? Does cwd exist?
  • http: Is url accessible? Does it require authentication headers? Is it blocked by corporate proxy/certificates?
• Check notifications/errors: The interface will display connection failure reasons or stderr output snippets.
• Increase timeout appropriately (in seconds) to avoid false failures caused by short timeouts.
• If you are developing a local server:
  • Check if the build artifact (e.g., build/index.js) has been generated and is executable.
  • After changing build artifacts, wait for automatic restart; if it doesn't take effect, try "Disable → Enable".

2. Tools or Resources are empty

• Is the server connected? If not connected, troubleshoot connection issues first.
• Does the MCP server itself not expose tools/resources? Check its repository documentation to confirm.
• http type: Are authentication/headers correct? Is it returning 401/403?
• stdio type: Does stderr indicate missing dependencies/initialization failures?

3. Call timeout or instability

• Increase timeout.
• Prefer network nodes or services that are more stable or closer.
• For http type, ensure proxy/gateway does not interrupt long connections/streaming connections.
• When server load is high or cold start is slow, appropriately extend waiting time.

4. Permission/security related issues

• Be cautious when setting env and headers (especially fields containing credentials) to avoid leakage.
• Only add trusted tools to autoApprove whitelist to avoid risks from bypassing secondary confirmation.
• If the server can access local files or internal networks, follow the principle of least privilege and isolation (only open directories/interfaces that are needed).

5. Other troubleshooting approaches

• Execute the target command for minimal reproduction: Manually run command/args in the terminal to confirm if it can start independently.
• Check the server repository's README/issues for known problems and solutions.
• Include necessary information when submitting issues: Configuration snippets (with sensitive data redacted), logs/notification content, system and network environment descriptions.

Best Practices

Server selection

• Prioritize servers that are actively maintained and have good community reputation.
• Use official directories and curated collections for quick filtering:
  • modelcontextprotocol/servers
  • punkpeye/awesome-mcp-servers
  • Directory sites (see "Resources").

Security

• Least privilege: Only expose necessary resources/directories/networks.
• Be cautious with autoApprove: Only add tools that are confirmed to be safe to the whitelist.
• Review env/headers: Avoid hardcoding tokens/keys in shared environments.

Performance and stability

• Adjust timeout based on network and service performance.
• For http type, ensure proxy and load balancer are friendly to SSE/streaming responses.
• For local development servers, leverage automatic restart triggered by build artifact changes to speed up debugging iterations.

Maintainability

• Unified naming and grouping: Use prefixes for servers of the same type to facilitate search and sorting.
• Regularly backup configuration files; perform minimal verification before and after changes.

Resources

GitHub repositories

• modelcontextprotocol/servers
• punkpeye/awesome-mcp-servers

Online directories

• mcpservers.org
• mcp.so
• glama.ai/mcp/servers

PulseMCP

• www.pulsemcp.com

Tutorial videos

• AI-Driven Coder (Building and using MCP servers):
  • YouTube video

FAQ

Q: Why don't I see an "Execute immediately" button when I click on a tool?

A: Tools are often called in chat or automated workflows; the interface-level "Enable/Disable" is for temporarily controlling availability and does not directly trigger execution.

Q: Can I combine command and args into one line in the configuration?

A: Yes. If args is not provided and there are spaces in command, Chaterm will automatically parse it (supports quotes and escaping).

Q: How do I manually restart a server?

A: If automatic restart is not triggered, you can reconnect by "Disable → Enable".

Q: What are the risks of autoApprove?

A: When enabled, matching tools will automatically approve execution. Please only enable this for trusted, predictable tools to reduce the risk of misoperation or unauthorized access.