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
- Connection failures - Network timeouts, unreachable servers
- Authentication errors - Token issues, invalid credentials
- Tool discovery problems - Tools not appearing, listing failures
- Communication errors - Request/response failures
- Performance issues - Slow responses, timeouts
- Configuration problems - Incorrect parameters, headers
Troubleshooting Approach
- Identify the transport method in use (Hosted, HTTP, SSE, stdio)
- Check basic connectivity to the MCP server
- Verify authentication credentials and tokens
- Validate server configuration parameters
- Test tool listing functionality
- Examine error messages for specific details
- 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