Skip to main content

​
Installation Issues

​
uvx Command Not Found

Problem: uvx: command not found when trying to run tools 
# Install uv using official installer
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to PATH (Linux/macOS)
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh users
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify installation
uvx --version

# Install using pip
pip install uv

# Verify
uvx --version

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Verify
uvx --version

​
Python Version Mismatch

Problem: Error: Python 3.10+ required, found Python 3.9 Solution: 
# Check current Python version
python3 --version

# Install Python 3.10+ (Ubuntu/Debian)
sudo apt update
sudo apt install python3.10

# macOS (using Homebrew)
brew install python@3.10

# Windows
# Download from https://www.python.org/downloads/

# Verify
python3.10 --version

​
Permission Denied

Problem: Permission denied when installing or running tools

​
Dependency Conflict

Problem: Unable to resolve dependencies or package version conflicts Solution: 
# Clear uv cache
uv cache clean

# Reinstall with clean cache
uvx --refresh automagik-tools

# If still failing, create isolated environment
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate  # Windows

pip install automagik-tools

​
Runtime Errors

​
Tool Not Responding

Problem: MCP tool executes but returns no response Solutions: 
# Test if API is accessible
curl -I https://api.example.com

# If API requires authentication
curl -H "Authorization: Bearer $API_KEY" https://api.example.com

# Check if URL is correct in tool configuration
Update MCP configuration to allow longer timeouts:
{
  "mcpServers": {
    "my-api-tool": {
      "command": "uvx",
      "args": ["automagik-tools", "mcp", "--spec", "spec.json"],
      "timeout": 60000  // Increase to 60 seconds
    }
  }
}

# Enable debug logging
uvx automagik-tools mcp --spec spec.json --debug

# Check MCP server logs
# Claude Code: ~/.claude/logs/
# Cursor: Help → Show Logs → MCP

​
Memory Issues with Large Responses

Problem: Tool crashes or hangs with large API responses Solution: 
# Limit response size in OpenAPI spec
# Add maxLength constraint to large fields

# Example OpenAPI modification:
{
  "schema": {
    "type": "string",
    "maxLength": 10000  # Limit to 10KB
  }
}

# Or use pagination if API supports it
{
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "schema": {
        "type": "integer",
        "default": 100,
        "maximum": 1000
      }
    }
  ]
}

​
Network Timeout Errors

Problem: Request timeout or Connection timed out Solutions: 
# Check network connectivity
ping api.example.com

# Test API directly
curl -v https://api.example.com/endpoint

# Configure proxy if needed
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# Disable proxy temporarily to test
unset HTTP_PROXY
unset HTTPS_PROXY

# Increase timeout in tool config
uvx automagik-tools mcp --spec spec.json --timeout 120

​
API Rate Limiting

Problem: 429 Too Many Requests or rate limit errors Solution: 
# Implement rate limiting in usage
# Wait between requests

# Add retry logic in tool configuration
{
  "retry": {
    "max_attempts": 3,
    "backoff_seconds": 5
  }
}

# Check API documentation for rate limits
# Example: 100 requests per minute

# Use API key with higher limits if available
export API_KEY=your_premium_key

​
Configuration Issues

​
Environment Variables Not Loaded

Problem: Tool can’t find API keys or configuration Solutions: 
# Check if variable is set
echo $API_KEY
echo $OPENAI_API_KEY

# Should output the key value
# If empty, variable is not set

{
  "mcpServers": {
    "my-api-tool": {
      "command": "uvx",
      "args": ["automagik-tools", "mcp", "--spec", "spec.json"],
      "env": {
        "API_KEY": "your-api-key-here",
        "BASE_URL": "https://api.example.com"
      }
    }
  }
}

# Create .env file
cat > .env << EOF
API_KEY=your-api-key-here
BASE_URL=https://api.example.com
EOF

# Load in shell
export $(cat .env | xargs)

# Or use direnv for automatic loading
# Install: brew install direnv (macOS)
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc

​
Tool Not Found in AI Client

Problem: MCP tool doesn’t appear in Claude/Cursor tool list Solutions:
1

Verify MCP Configuration

Check that the MCP server is properly configured:
# Claude Code
cat ~/.claude/mcp.json

# Cursor
# Settings → MCP → Check server list
2

Test MCP Server Directly

# Run in stdio mode and test
uvx automagik-tools mcp --spec spec.json

# Should output: "MCP server running in stdio mode"
# Press Ctrl+C to exit
3

Restart AI Client

# Claude Code: Reload MCP servers
# Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
# Type: "Reload MCP Servers"

# Cursor: Reload window
# Cmd+R (macOS) or Ctrl+R (Windows/Linux)
4

Check Logs for Errors

# Claude Code logs
tail -f ~/.claude/logs/mcp.log

# Look for error messages related to tool loading

​
Invalid OpenAPI Specification

Problem: Tool fails to load with spec validation errors Solution: 
# Validate OpenAPI spec
uvx automagik-tools validate --spec spec.json

# Common issues to fix:
# 1. Missing required fields
# 2. Invalid schema references
# 3. Incorrect data types
# 4. Missing server URL

# Use OpenAPI validator online
# https://editor.swagger.io
# Paste your spec and check for errors

# Fix common issues:
{
  "openapi": "3.0.0",  // Must be 3.0.0 or higher
  "info": {
    "title": "Required",
    "version": "1.0.0"  // Required
  },
  "servers": [{
    "url": "https://api.example.com"  // Required
  }],
  "paths": {}  // At least one path required
}

​
Performance Issues

​
Slow Tool Execution

Problem: Tools take very long to execute Solutions: 
# Measure API response time
time curl https://api.example.com/endpoint

# If API is slow, not much you can do
# Consider caching results

# Remove unnecessary fields from responses
# Use smaller page sizes
# Filter results at API level

# Example: Only request needed fields
{
  "parameters": [{
    "name": "fields",
    "in": "query",
    "schema": {
      "type": "string",
      "example": "id,name,status"  // Only these fields
    }
  }]
}

# Cache API responses
uvx automagik-tools mcp --spec spec.json --cache-ttl 300

# TTL in seconds (300 = 5 minutes)

​
High Memory Usage

Problem: Tool consuming excessive memory Solution: 
# Limit response payload size
# Add pagination to large collections
# Stream large responses instead of loading all at once

# In OpenAPI spec:
{
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "type": "array",
            "maxItems": 100  // Limit array size
          }
        }
      }
    }
  }
}

# Use streaming where supported
# Check API documentation for streaming endpoints

​
Platform-Specific Issues

​
Windows Path Issues

Problem: Spec file not found on Windows Solution: 
# Use forward slashes or escaped backslashes
uvx automagik-tools mcp --spec "C:/path/to/spec.json"
# or
uvx automagik-tools mcp --spec "C:\\path\\to\\spec.json"

# Use relative paths
cd C:\project
uvx automagik-tools mcp --spec ".\openapi.json"

# Or use Windows Subsystem for Linux (WSL)
wsl
uvx automagik-tools mcp --spec spec.json

​
macOS Gatekeeper Issues

Problem: macOS blocks execution with security warning Solution: 
# Allow uv in System Preferences
# System Preferences → Security & Privacy → General
# Click "Allow" next to the warning about uv

# Or remove quarantine attribute
xattr -d com.apple.quarantine ~/.cargo/bin/uv

# Verify
uvx --version

​
Linux Library Missing

Problem: error while loading shared libraries Solution: 
# Install missing libraries (Ubuntu/Debian)
sudo apt update
sudo apt install -y build-essential libssl-dev libffi-dev python3-dev

# CentOS/RHEL
sudo yum install -y gcc openssl-devel libffi-devel python3-devel

# Arch Linux
sudo pacman -S base-devel openssl libffi

# Verify
uvx automagik-tools --version

​
Next Steps

Installation Errors

Detailed installation troubleshooting

MCP Connection Errors

MCP client configuration issues

OpenAPI Conversion

OpenAPI specification problems

FAQ

Frequently asked questions