Troubleshooting

Find solutions to frequently encountered problems with WISTX MCP server, API connections, and tool integrations.

MCP Server Issues

MCP Server Not Starting

Symptoms:

MCP server fails to start
Error messages about missing dependencies
Connection errors in your coding agent
“Command not found” errors

Solutions:

Check Python Version

WISTX requires Python 3.11 or higher. Verify your Python version:

python --version
# or
python3 --version

If you need to upgrade:

macOS: brew install python@3.11 or download from python.org
Linux: Use your package manager (e.g., sudo apt install python3.11)
Windows: Download from python.org

Python 3.8, 3.9, and 3.10 are not supported. You must use Python 3.11 or higher.

Check pipx/uvx Installation

Verify pipx or uvx is installed and working:

# Check pipx
pipx --version

# Check uvx (if using uvx)
uvx --version

If not installed:

pipx: pip install --user pipx && pipx ensurepath
uvx: Install via uv - curl -LsSf https://astral.sh/uv/install.sh | sh

Reinstall WISTX MCP

Try reinstalling the package:

# Using pipx (recommended)
pipx uninstall wistx-mcp
pipx install wistx-mcp

# Using uvx
# uvx doesn't require pre-installation, but you can clear cache
rm -rf ~/.cache/uvx

Verify installation:

pipx run wistx-mcp --help

Clear pipx Cache (Stale Version Issues)

If you see errors from an old version after updating, pipx may be using a cached version.Symptoms:

Errors mention files or imports that should have been fixed
Tool count doesn’t match expected (e.g., 20 tools instead of 21)

Solution - Clear ALL pipx caches:

# Clear pipx run cache
rm -rf ~/.local/pipx/.cache/*

# Also clear pip's HTTP and wheel cache (used during install)
rm -rf ~/.cache/pip/
rm -rf ~/Library/Caches/pip/  # macOS specific

# Reinstall fresh
pipx uninstall wistx-mcp 2>/dev/null || true
pipx install wistx-mcp --force

Verify the correct version is installed:

# Check installed version
pipx list | grep wistx-mcp

# Check the import in user_indexing.py is correct
grep "normalize_repo_url" ~/.local/pipx/venvs/wistx-mcp/lib/python*/site-packages/wistx_mcp/tools/user_indexing.py
# Should show: from wistx_mcp.tools.lib.repo_normalizer import normalize_repo_url

After clearing cache, restart your coding agent completely (Cmd+Q on macOS). The MCP server process may still have the old code loaded in memory.

Check Configuration File Syntax

Verify your MCP configuration file syntax is valid JSON:

{
  "mcpServers": {
    "wistx": {
      "command": "pipx",
      "args": ["run", "--no-cache", "wistx-mcp"],
      "env": {
        "WISTX_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Common issues:

Missing commas between properties
Unclosed brackets or braces
Trailing commas (not allowed in JSON)
Incorrect environment variable names (should be WISTX_API_KEY, not API_KEY)
Quotes around environment variable values (not needed)

Validate JSON syntax:

# macOS/Linux
python3 -m json.tool ~/.cursor/mcp.json

# Or use online JSON validator

Check API Key

Ensure your API key is correct and active:

Log in to wistx.ai/api-key
Navigate to API Keys section
Verify the key is active (not revoked or expired)
Copy the key again and update your configuration

Make sure there are no extra spaces or quotes around the API key in your configuration
The API key should be a string value, not wrapped in quotes in the JSON
Environment variable names are case-sensitive: WISTX_API_KEY not wistx_api_key

Test your API key:

curl -X POST https://api.wistx.ai/v1/compliance/requirements \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource_types": ["RDS"], "standards": ["PCI-DSS"]}'

Check MCP Client Configuration Path

Verify you’re editing the correct configuration file for your coding agent:

Cursor: ~/.cursor/mcp.json (macOS/Linux) or %APPDATA%\Cursor\mcp.json (Windows)
Windsurf: ~/.windsurf/mcp.json (macOS/Linux) or %APPDATA%\Windsurf\mcp.json (Windows)
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
VS Code: ~/.config/Code/User/mcp.json (macOS/Linux) or %APPDATA%\Code\User\mcp.json (Windows)
Continue.dev: ~/.continue/config.json

Some clients may require creating the directory if it doesn’t exist.

MCP Tools Not Available

Symptoms:

Tools don’t appear in your coding agent
“Tool not found” errors
Empty tool list
“Unknown tool” errors

Solutions:

Restart Your Coding Agent

After configuring WISTX MCP, you must completely restart your coding agent:

Cursor: Quit completely (Cmd+Q on macOS, Alt+F4 on Windows) and reopen
Claude Desktop: Quit completely and reopen
VS Code: Reload the window (Cmd/Ctrl + Shift + P → “Developer: Reload Window”)
Windsurf: Restart Windsurf completely
Continue.dev: Restart Continue.dev extension
Gemini CLI: Restart the CLI session

Simply closing and reopening a window may not be enough. Ensure the application process is fully terminated.

Check MCP Server Logs

Check logs for errors:

Cursor: Check ~/.cursor/logs/ or use Cursor’s built-in log viewer
Claude Desktop: Check ~/Library/Application Support/Claude/logs/ (macOS) or %APPDATA%\Claude\logs\ (Windows)
VS Code: Check Output panel → Select “MCP Server” from dropdown
Windsurf: Check ~/.windsurf/logs/

Look for errors like:

ValueError: api_key is required
RuntimeError: Failed to start MCP server
ConnectionError: Network connection failed

Verify API Key Authentication

Test your API key directly:

curl -X POST https://api.wistx.ai/v1/compliance/requirements \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource_types": ["RDS"], "standards": ["PCI-DSS"]}'

Expected response: JSON with compliance requirementsIf you get 401 Unauthorized:

Your API key is invalid or expired
Check the key in wistx.ai/api-key
Regenerate if needed

If you get 429 Too Many Requests:

You’ve exceeded your rate limit
Check your plan limits
Wait or upgrade your plan

Test MCP Server Manually

Test if the MCP server can start manually:

# Using pipx
pipx run wistx-mcp

# Using uvx
uvx wistx-mcp

If it starts successfully, you should see log output. Press Ctrl+C to stop.If it fails:

Check Python version (must be 3.11+)
Check pipx/uvx installation
Check network connectivity

Check Tool Name Format

Ensure you’re using the correct tool names. All WISTX tools start with wistx_:

wistx_get_compliance_requirements ✓
wistx_calculate_infrastructure_cost ✓
wistx_search_code ✓ (unified code search)
wistx_infrastructure ✓ (unified infrastructure)
wistx_context ✓ (unified context management)
wistx_index ✓ (unified indexing)
wistx_research ✓ (unified research)
wistx_packages ✓ (unified packages)
get_compliance_requirements ✗ (missing prefix)

If your coding agent shows “Unknown tool” errors, verify the tool name matches exactly.

Expected Startup Warnings (Not Errors)

Some warnings during MCP server startup are normal and expected. These do not affect functionality.

OpenAI API Key Not Configured

Log message:

WARNING - OpenAI API key not configured - AI analysis will be disabled

Impact: None for normal operation. AI-powered analysis features (like enhanced resource insights) are optional and disabled when the key isn’t configured.Resolution: This is expected behavior. The OpenAI API key is configured on the backend, not required for MCP server operation.

Authentication Service Temporarily Unavailable (Local Development)

Log message:

ERROR - Error listing MCP resources: Authentication service temporarily unavailable
ERROR - All connection attempts failed

Impact: Only affects listing indexed resources in the MCP “Resources” panel (shows 0 resources). All tools still register and work normally.Why this happens: When running locally without the backend API, the MCP server cannot authenticate to list your indexed resources. This is expected for local development.What to check:

Tools are registered: Look for Found 21 tools in logs ✓
All functionality works when connected to production backend

Resolution: No action needed for local development. When connected to production (api.wistx.ai), authentication will succeed.

MCP SDK Version Warnings

Log messages:

WARNING - MCP SDK version may not support on_initialize decorator
WARNING - on_initialize handler not registered - SDK will handle initialization automatically

Impact: None. These are compatibility warnings for different MCP SDK versions.Resolution: No action needed. The server handles both old and new SDK versions automatically.

Tool Execution Errors

Validation Errors (ValueError)

Symptoms:

ValueError: api_key is required
ValueError: At least one resource type is required
ValueError: Query must be at least 10 characters
ValueError: Invalid search_type
Parameter validation errors

Solutions:

Missing Required Parameters

Most WISTX tools require an api_key parameter. Ensure you’re passing it:

{
  "resource_types": ["RDS"],
  "api_key": "YOUR_API_KEY"
}

Common missing parameters:

wistx_get_compliance_requirements: Requires resource_types
wistx_search_code: Requires search_mode and query
wistx_research: Requires source and query (min 10 chars for knowledge_base)
wistx_index: Requires action (and repo_url for repository action)

Note: API key is no longer passed as a tool parameter. It’s automatically injected from your environment variable (WISTX_API_KEY) or MCP initialization.

Check the Tools & Features page for required parameters for each tool.

Invalid Parameter Values

Check parameter formats and constraints:

Query length: wistx_research with source="knowledge_base" requires queries of at least 10 characters
Search mode: wistx_search_code accepts "semantic", "regex", or "examples"
Research source: wistx_research accepts "knowledge_base", "web", "security", or "all"
Severity: Must be one of "CRITICAL", "HIGH", "MEDIUM", "LOW" (case-sensitive)
Resource types: Must be an array, not a string
Cloud provider: Must be "aws", "gcp", or "azure" (lowercase)

Example of correct format:

{
  "resource_types": ["RDS", "S3"],
  "standards": ["PCI-DSS", "HIPAA"],
  "severity": "HIGH",
  "api_key": "YOUR_API_KEY"
}

Regex Search Errors

For wistx_search_code with search_mode="regex", you must provide either pattern OR template:

{
  "pattern": "api_key.*=.*['\"](.*)['\"]",
  "api_key": "YOUR_API_KEY"
}

{
  "template": "api_key",
  "api_key": "YOUR_API_KEY"
}

Common errors:

Providing both pattern and template (use only one)
Pattern exceeds 10,000 characters
Invalid regex syntax

Runtime Errors

Symptoms:

RuntimeError: Rate limit exceeded
RuntimeError: Server error: 500
RuntimeError: HTTP error: 404
RuntimeError: Failed to start MCP server

Solutions:

Rate Limit Exceeded

If you see RuntimeError: Rate limit exceeded:

Check your current usage in wistx.ai/api-key dashboard
Verify your plan limits:

Professional: 2,000 queries/month
Team: 10,000 queries/month
Enterprise: Unlimited queries

Wait for the rate limit to reset (monthly)
Upgrade your plan if needed

Rate limits reset monthly based on your billing cycle.

Server Errors (5xx)

If you see RuntimeError: Server error: 500 or similar:

Check status.wistx.ai for service status
Wait a few minutes and retry
If the issue persists, contact support with:
- Error message
- Tool name
- Timestamp
- Request details

Resource Not Found (404)

If you see RuntimeError: HTTP error: 404:

Verify the repository URL is correct (for indexing tools)
Check if the resource exists
Ensure you have access to the resource
For private repositories, verify GitHub OAuth is connected

Connection and Timeout Errors

Symptoms:

ConnectionError: Network connection failed
TimeoutError: Request timeout
Slow responses
Intermittent failures

Solutions:

Network Connectivity

Verify your internet connection:

# Test connectivity to WISTX API
curl -I https://api.wistx.ai/health

# Test DNS resolution
nslookup api.wistx.ai

# Test with ping
ping api.wistx.ai

Expected: HTTP 200 response from health endpoint

Firewall/Proxy Issues

Ensure firewall/proxy allows connections to:

api.wistx.ai (port 443, HTTPS)
app.wistx.ai (port 443, HTTPS)

If behind a corporate firewall:

Contact your IT department
Request whitelist for *.wistx.ai domains
Provide firewall rules if needed

For proxy configuration, set environment variables:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

Timeout Issues

For large operations (indexing, complex searches), timeouts may occur:

Indexing: Large repositories may take 30+ minutes
Regex search: Complex patterns on large codebases may timeout
Package search: Large result sets may take longer

Solutions:

Use wistx_manage_resources with action='status' to monitor indexing progress
Break large searches into smaller queries
Use filters to narrow results
Increase timeout if using REST API directly

API Issues

Authentication Errors

Symptoms:

401 Unauthorized errors
Invalid API key messages
api_key is required errors
Authentication failures

Solutions:

Check API Key Format

Ensure your API key is in the correct format:For REST API:

Authorization: Bearer YOUR_API_KEY

For MCP Tools:

{
  "api_key": "YOUR_API_KEY"
}

Common mistakes:

Missing Bearer prefix in REST API calls
Extra spaces before/after the key
Using quotes around the key in JSON (not needed)
Including sk- or other prefixes (WISTX keys don’t have prefixes)

Verify API Key Status

Log in to wistx.ai/api-key
Navigate to API Keys section
Check if the key is:
- Active (not revoked)
- Not expired
- Has proper permissions
Regenerate if needed (old key will be invalidated)

Regenerating an API key will invalidate the old key immediately. Update all configurations.

Check API Key in MCP Configuration

Verify the API key is correctly set in your MCP configuration:

{
  "mcpServers": {
    "wistx": {
      "command": "pipx",
      "args": ["run", "--no-cache", "wistx-mcp"],
      "env": {
        "WISTX_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

Common issues:

Key wrapped in quotes: "WISTX_API_KEY": "\"key\"" ✗
Extra spaces: "WISTX_API_KEY": " key " ✗
Wrong variable name: "API_KEY" instead of "WISTX_API_KEY" ✗

Rate Limit Errors

Symptoms:

429 Too Many Requests errors
Rate limit exceeded messages
Quota exceeded errors

Solutions:

Check Your Plan Limits

Current plan limits:

Plan	Queries/Month	Index Jobs/Month
Professional	2,000	5
Team	10,000	10
Enterprise	Unlimited	Unlimited

View your current usage in the dashboard.

Queries include all tool calls (compliance, pricing, search, etc.). Index jobs are separate.

Monitor Usage

Check your usage before hitting limits:

Log in to wistx.ai/api-key
Go to Usage or Dashboard
View:
- Queries used this month
- Index jobs used
- Remaining quota
- Reset date

Rate limits reset monthly based on your billing cycle, not calendar month.

Optimize Tool Usage

Reduce unnecessary tool calls:

Cache results when possible
Use filters to narrow searches
Batch multiple resource types in a single compliance query
Use wistx_research with source="all" instead of multiple separate searches

Example of efficient batching:

{
  "resource_types": ["RDS", "S3", "EC2"],
  "standards": ["PCI-DSS", "HIPAA"],
  "api_key": "YOUR_API_KEY"
}

Upgrade Your Plan

If you consistently hit rate limits:

Visit wistx.ai/api-key
Go to Billing or Plans
Select a higher plan
Limits increase immediately after upgrade

Upgrading mid-cycle prorates the cost. Downgrading takes effect at the end of the billing cycle.

Indexing Issues

Indexing Fails or Hangs

Symptoms:

Indexing job fails immediately
Indexing hangs indefinitely
“Repository access denied” errors
Slow indexing progress

Solutions:

Check Repository Access

For private repositories:

Connect GitHub OAuth (recommended):
- Log in to wistx.ai/api-key
- Go to Settings → Integrations
- Connect GitHub account
- Grant repository access permissions
Verify repository permissions:
- Ensure your GitHub account has access to the repository
- Check if repository is archived (archived repos may fail)
- Verify repository visibility (private repos require OAuth)

Test access manually:

# If using personal access token
curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/owner/repo

For public repositories, no GitHub token is needed. For private repositories, OAuth is recommended over personal access tokens.

Check Repository Size and Structure

Very large repositories may take longer to index:

Small repos (< 100MB): Usually completes in 1-5 minutes
Medium repos (100MB - 1GB): May take 10-30 minutes
Large repos (> 1GB): May take 30+ minutes

Monitor progress:

# Use the check status tool
{
  "resource_id": "res_abc123",
  "api_key": "YOUR_API_KEY"
}

Optimize indexing:

Use exclude_patterns to skip unnecessary files:

{
  "exclude_patterns": [
    "**/node_modules/**",
    "**/dist/**",
    "**/.git/**",
    "**/vendor/**",
    "**/build/**"
  ]
}

Use include_patterns to focus on DevOps files:

{
  "include_patterns": [
    "**/*.tf",
    "**/*.yaml",
    "**/*.yml",
    "**/terraform/**",
    "**/k8s/**"
  ]
}

Check Indexing Quota

Verify you haven’t exceeded indexing quota:

Professional: 5 index jobs/month
Team: 10 index jobs/month
Enterprise: Unlimited index jobs

Check your usage:

Log in to wistx.ai/api-key
Go to Resources or Usage
View indexed resources and remaining quota

Deleting and re-indexing the same resource counts as a new index job.

Repository URL Format

Ensure repository URL is correct:Correct formats:

https://github.com/owner/repo
https://github.com/owner/repo.git

Incorrect formats:

git@github.com:owner/repo.git (SSH format not supported)
owner/repo (missing protocol)
github.com/owner/repo (missing protocol)

For branch specification:

{
  "repo_url": "https://github.com/owner/repo",
  "branch": "main",
  "api_key": "YOUR_API_KEY"
}

Documentation Website Indexing

For wistx_index_resource with documentation websites:Common issues:

Website requires authentication (not supported)
Website blocks crawlers (check robots.txt)
Very large websites (> 10,000 pages may timeout)
Dynamic content (JavaScript-rendered content may not be indexed)

Solutions:

Use include_patterns to limit scope:

{
  "content_url": "https://docs.example.com",
  "include_patterns": ["/docs/", "/api/"],
  "exclude_patterns": ["/admin/", "/private/"]
}

Index specific sections separately
Use PDF/DOCX upload for static documentation

Indexing Status Issues

Symptoms:

Status stuck on “indexing”
Status shows “failed” but no error message
Can’t check status

Solutions:

Check Resource Status

Use wistx_manage_resources with action='status' to monitor progress:

{
  "action": "status",
  "resource_id": "res_abc123",
  "api_key": "YOUR_API_KEY"
}

Status values:

pending: Job queued, waiting to start
indexing: Currently processing
completed: Successfully indexed
failed: Indexing failed (check error message)

Recommended: Check status at reasonable intervals (every 30-60 seconds) after initiating indexing, or when the user asks about progress.

Resource ID is returned when you start indexing. Save it to check status later.

Handle Failed Indexing

If indexing fails:

Check the error message in status response
Common causes:
- Repository access denied (check GitHub OAuth)
- Repository too large (use exclude_patterns)
- Network timeout (retry)
- Invalid repository URL
Retry indexing with adjusted parameters
Contact support if issue persists

List All Resources

Use wistx_manage_resources with action='list' to see all indexed resources:

{
  "action": "list",
  "api_key": "YOUR_API_KEY"
}

Filter by status:

{
  "action": "list",
  "status_filter": "completed",
  "api_key": "YOUR_API_KEY"
}

Filter by resource type:

{
  "action": "list",
  "resource_type": "repository",
  "api_key": "YOUR_API_KEY"
}

Search and Query Issues

No Results Found

Symptoms:

Search returns empty results
“No matches found” messages
Expected results not appearing

Solutions:

Check Indexed Resources

Ensure resources are indexed before searching:

Use wistx_manage_resources with action='list' to see indexed resources
Verify the repository/documentation you’re searching is indexed
Check indexing status is “completed”
Re-index if needed

wistx_search_code only searches your indexed resources. It won’t search unindexed repositories.

Broaden Search Query

Try broader search terms:

Instead of: “RDS encryption configuration”
Try: “RDS encryption” or “encryption”

Use natural language queries:

{
  "query": "How do I configure RDS encryption?",
  "api_key": "YOUR_API_KEY"
}

Check Filters

Remove restrictive filters:

Try without code_type filter
Try without cloud_provider filter
Try without file_types filter
Check repositories filter matches indexed repos

Example without filters:

{
  "query": "Terraform RDS configuration",
  "api_key": "YOUR_API_KEY"
}

Use Different Search Tools

Try alternative search approaches using the unified wistx_search_code tool:

Semantic search: wistx_search_code with search_mode="semantic" (natural language)
Pattern search: wistx_search_code with search_mode="regex" (exact patterns)
Code examples: wistx_search_code with search_mode="examples" (curated examples)
Package search: wistx_packages with action="search" (for packages)
Research: wistx_research with source="knowledge_base" (general knowledge)

Getting Help

If you’re still experiencing issues:

Check Documentation:
Check Service Status:
- Visit status.wistx.ai for service status
Search Existing Issues:
- Check GitHub Issues for similar problems
Contact Support:
- Email: hi@wistx.ai
- Include:
  - Error messages (full text)
  - Tool name and parameters used
  - Request IDs (from response metadata)
  - Steps to reproduce
  - Your plan type
  - Python version (python --version)
  - Coding agent and version
Community:
- Join our Discord community for real-time support and discussions
- Visit our GitHub repository to report issues and contribute
- Check GitHub Discussions for community Q&A

When contacting support, please include:

Complete error messages
Tool name and parameters
Request IDs (if available)
Steps to reproduce the issue
Your plan type (Professional/Team/Enterprise)
Python version
Coding agent name and version
MCP configuration (with API key redacted)

Get Started

MCP Integration

Guides

API Reference

Resources

MCP Server Issues

MCP Server Not Starting

MCP Tools Not Available

Expected Startup Warnings (Not Errors)

Tool Execution Errors

Validation Errors (ValueError)

Runtime Errors

Connection and Timeout Errors

API Issues

Authentication Errors

Rate Limit Errors

Indexing Issues

Indexing Fails or Hangs

Indexing Status Issues

Search and Query Issues

No Results Found

Getting Help

​MCP Server Issues

​MCP Server Not Starting

​MCP Tools Not Available

​Expected Startup Warnings (Not Errors)

​Tool Execution Errors

​Validation Errors (ValueError)

​Runtime Errors

​Connection and Timeout Errors

​API Issues

​Authentication Errors

​Rate Limit Errors

​Indexing Issues

​Indexing Fails or Hangs

​Indexing Status Issues

​Search and Query Issues

​No Results Found

​Getting Help

MCP Server Issues

MCP Server Not Starting

MCP Tools Not Available

Expected Startup Warnings (Not Errors)

Tool Execution Errors

Validation Errors (ValueError)

Runtime Errors

Connection and Timeout Errors

API Issues

Authentication Errors

Rate Limit Errors

Indexing Issues

Indexing Fails or Hangs

Indexing Status Issues

Search and Query Issues

No Results Found

Getting Help