MCP Server Troubleshooting Skill

This skill helps diagnose and resolve common issues with Model Context Protocol (MCP) server connections in OpenAI Agents SDK.

Purpose

• Identify common MCP connection problems
• Provide systematic troubleshooting steps
• Resolve authentication, network, and configuration issues
• Debug tool availability and communication problems

Common Issues Addressed

1. Connection failures - Network timeouts, unreachable servers
2. Authentication errors - Token issues, invalid credentials
3. Tool discovery problems - Tools not appearing, listing failures
4. Communication errors - Request/response failures
5. Performance issues - Slow responses, timeouts
6. Configuration problems - Incorrect parameters, headers

Troubleshooting Approach

1. Identify the transport method in use (Hosted, HTTP, SSE, stdio)
2. Check basic connectivity to the MCP server
3. Verify authentication credentials and tokens
4. Validate server configuration parameters
5. Test tool listing functionality
6. Examine error messages for specific details
7. Review logs for additional diagnostic information

Diagnostic Commands

• Test server reachability
• Validate authentication tokens
• Check tool listing endpoints
• Verify headers and parameters
• Review timeout configurations

Resolution Strategies

• Update authentication credentials
• Adjust timeout values
• Fix network configuration
• Correct server parameters
• Implement retry mechanisms
• Add proper error handling