Server Configuration Reference

This guide explains all the ways you can configure the WhoisXML API MCP Server, including which command-line flags and environment variables you can use, plus examples for different ways to set it up.

Command-Line Flags

The MCP server accepts the following command-line flags:

--api-base-url
- Type: string
- Default: https://www.whoisxmlapi.com
- Description: Custom API base URL for WhoisXMLAPI service
- Example: --api-base-url https://api.custom.com
--timeout
- Type: duration
- Default: 10s
- Description: Timeout for API requests to WhoisXMLAPI
- Example: --timeout 30s
--disabled-tools
- Type: string
- Default: (none)
- Description: Comma-separated list of tools to disable
- Example: --disabled-tools threat_intelligence,reverse_whois
--http
- Type: boolean
- Default: false
- Description: Enable HTTP server mode with streamable HTTP transport
- Example: --http
--http-port
- Type: integer
- Default: 3000
- Description: Port for HTTP server (when --http is enabled)
- Example: --http-port 8080
--help
- Type: boolean
- Default: false
- Description: Display help information
- Example: --help
--version
- Type: boolean
- Default: false
- Description: Display version information
- Example: --version

Usage Examples

Basic usage:

# Use with environment variable
WHOISXMLAPI_TOKEN=your-token mcp-whoisxmlapi

# Custom timeout
mcp-whoisxmlapi --timeout 30s

# Disable specific tools
mcp-whoisxmlapi --disabled-tools threat_intelligence,reverse_whois

# Enable HTTP server mode
mcp-whoisxmlapi --http --http-port 3000

Docker usage:

# Basic Docker with flags
docker run --rm -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 \
  --timeout 30s --disabled-tools threat_intelligence

# HTTP mode with Docker
docker run --rm -p 3000:3000 \
  -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 \
  --http --http-port 3000

npx usage (recommended):

# Using npx (no installation required)
npx @whoisxmlapidotcom/mcp-whoisxmlapi --timeout 30s

# Always runs latest version
npx @whoisxmlapidotcom/mcp-whoisxmlapi --timeout 30s --http

Environment Variables

Environment variables provide an alternative way to configure the server and are often preferred for sensitive information like API tokens.

Required Variables

WHOISXMLAPI_TOKEN
- Description: Your WhoisXMLAPI authentication token
- Type: string
- Example: "wxt-abc123def456..."

Optional Variables

WHOISXMLAPI_HTTP_DEBUG
- Description: Path to debug log file for HTTP request/response logging. Use "stderr" or "-" to log to stderr instead of a file.
- Type: string
- Default: (none)
- Example: "/tmp/whoisxmlapi-debug.log" or "stderr" or "-"
WHOISXMLAPI_DISABLED_TOOLS
- Description: Comma-separated list of tools to disable
- Type: string
- Default: (none)
- Example: "threat_intelligence,reverse_whois"
WHOISXMLAPI_TIMEOUT
- Description: API request timeout (alternative to --timeout flag)
- Type: duration
- Default: 10s
- Example: "30s"

Environment Variable Priority

Command-line flags take precedence over environment variables. For example, --timeout 30s will override WHOISXMLAPI_TIMEOUT=20s.

Setting Environment Variables

Shell (Linux/macOS):

# Temporary (current session only)
export WHOISXMLAPI_TOKEN="your-token-here"
export WHOISXMLAPI_HTTP_DEBUG="/tmp/whoisxmlapi-debug.log"  # or "stderr" to log to stderr
export WHOISXMLAPI_TIMEOUT="30s"

# Permanent (add to ~/.bashrc, ~/.zshrc, or ~/.profile)
echo 'export WHOISXMLAPI_TOKEN="your-token-here"' >> ~/.bashrc
echo 'export WHOISXMLAPI_HTTP_DEBUG="/tmp/debug.log"' >> ~/.bashrc
source ~/.bashrc

Windows:

# PowerShell (temporary)
$env:WHOISXMLAPI_TOKEN="your-token-here"
$env:WHOISXMLAPI_HTTP_DEBUG="C:\temp\debug.log"

# Command Prompt (temporary)
set WHOISXMLAPI_TOKEN=your-token-here
set WHOISXMLAPI_HTTP_DEBUG=C:\temp\debug.log

# Permanent: Use System Properties > Environment Variables

Docker:

# Using -e flag
docker run --rm -i \
  -e WHOISXMLAPI_TOKEN=your-token-here \
  -e WHOISXMLAPI_HTTP_DEBUG=/tmp/debug.log \
  -e WHOISXMLAPI_TIMEOUT=30s \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1

MCP Client Configuration Examples

These examples show how to configure the MCP server in various AI clients using different installation methods.

Docker Configuration (Recommended)

Basic Docker setup:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env", "WHOISXMLAPI_TOKEN",
        "whoisxmlapidotcom/mcp-whoisxmlapi:v1"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here"
      }
    }
  }
}

Docker with advanced options:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--memory=512m",
        "--cpus=1.0",
        "--env", "WHOISXMLAPI_TOKEN",
        "--env", "WHOISXMLAPI_HTTP_DEBUG",
        "--env", "WHOISXMLAPI_DISABLED_TOOLS",
        "-v", "/tmp:/tmp",
        "whoisxmlapidotcom/mcp-whoisxmlapi:v1",
        "--timeout", "30s"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here",
        "WHOISXMLAPI_HTTP_DEBUG": "/tmp/whoisxmlapi-debug.log",
        "WHOISXMLAPI_DISABLED_TOOLS": "threat_intelligence"
      }
    }
  }
}

npx Configuration (Recommended)

Using npx (no installation required):

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "npx",
      "args": [
        "-y",
        "@whoisxmlapidotcom/mcp-whoisxmlapi"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here"
      }
    }
  }
}

Why npx?

No installation required - Runs directly without package management
Always latest version - Automatically fetches the current release
Zero maintenance - No updates or dependency management needed

Alternative: Using global installation:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "mcp-whoisxmlapi",
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here"
      }
    }
  }
}

npx with custom options:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "npx",
      "args": [
        "-y",
        "@whoisxmlapidotcom/mcp-whoisxmlapi",
        "--timeout", "30s",
        "--disabled-tools", "threat_intelligence"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here",
        "WHOISXMLAPI_HTTP_DEBUG": "/tmp/debug.log"
      }
    }
  }
}

Binary Configuration

Basic binary setup:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "/usr/local/bin/mcp-whoisxmlapi",
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here"
      }
    }
  }
}

Binary with custom options:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "/usr/local/bin/mcp-whoisxmlapi",
      "args": [
        "--timeout", "30s",
        "--disabled-tools", "threat_intelligence,reverse_whois",
        "--api-base-url", "https://custom-api.example.com"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here",
        "WHOISXMLAPI_HTTP_DEBUG": "/tmp/whoisxmlapi-debug.log"
      }
    }
  }
}

Use Absolute Paths

Always use absolute paths for binary installations (e.g., /usr/local/bin/mcp-whoisxmlapi) rather than relative paths or just the binary name.

Tool Management

Disabling Specific Tools

You can disable specific tools to reduce functionality, improve startup performance, or work around client limitations.

Why Disable Tools?

Some MCP clients have limits on the number of tools (usually 30 to 40)
Reduce memory usage and startup time
Disable tools not relevant to your use case
Troubleshoot specific tool-related issues

Available tool names: See Tools Reference for the complete list.

Methods to disable tools:

Environment variable:

WHOISXMLAPI_DISABLED_TOOLS="threat_intelligence,reverse_whois,whois_history"

Command-line flag:

mcp-whoisxmlapi --disabled-tools threat_intelligence,reverse_whois

Configuration examples:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "mcp-whoisxmlapi",
      "args": ["--disabled-tools", "threat_intelligence,reverse_whois"],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token",
        "WHOISXMLAPI_DISABLED_TOOLS": "whois_history"
      }
    }
  }
}

HTTP Server Mode

For web applications or multiple client scenarios:

# Enable HTTP mode
mcp-whoisxmlapi --http --http-port 3000

# Docker HTTP mode
docker run --rm -p 3000:3000 \
  -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 \
  --http --http-port 3000

For complete HTTP server configuration details, see HTTP Server Mode.

Security Considerations

API Token Security

Never commit tokens to version control
Use environment variables for token storage
Rotate tokens regularly for enhanced security
Use separate tokens for different environments (dev/staging/prod)

Container Security (Docker)

No filesystem access by default - container is isolated
Limited environment - only explicitly passed variables are available
Network isolation - only internet access for API calls
Volume mounts - only mount necessary directories for debugging

Validation and Testing

Verify Configuration

# Test server startup
mcp-whoisxmlapi --help

# Test with token
WHOISXMLAPI_TOKEN=your-token mcp-whoisxmlapi --help

# Test specific configuration
docker run --rm -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 \
  --timeout 5s --disabled-tools threat_intelligence

Configuration Validation

Most configuration issues are JSON syntax errors:

# Validate JSON configuration
python -m json.tool your-config.json
# or
jq . your-config.json

Remove tokens

Whenever sharing configuration files, remove the WHOISXMLAPI_TOKEN before validating with online tools.

Installation and Setup

Installation Guide - Choose installation method
AI Client Configuration - Client-specific setup
Tools Reference - Available tools and usage

Advanced Features

HTTP Server Mode - Streamable HTTP transport configuration
HTTP Debugging - Request/response logging

Troubleshooting

General Troubleshooting - Common issues
Docker Troubleshooting - Container issues
npx Troubleshooting - npx and Node.js issues
Binary Troubleshooting - Binary installation issues