How do I use TuxCare ePortal MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TuxCare ePortal MCP Server list servers in the production environment" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

TuxCare ePortal MCP Server

A Model Context Protocol (MCP) server for integrating with TuxCare ePortal API. This server provides MCP tools for managing servers, feeds, registration keys, patchsets, and users through the ePortal API.

Features

Server Management: List, register, and unregister servers with advanced filtering
Feed Management: Create, modify, and delete feeds
Key Management: Manage registration keys for server enrollment
Patchset Management: List and manage patchset deployments
User Management: List ePortal users
Server Tagging: Set and manage server tags
Flexible Authentication: Support for basic auth and API keys

Related MCP server: MCP REST Server

Installation Options

Option 1: NPM Global Installation (Recommended)

# Install globally from npm
npm install -g tuxcare-eportal-mcp

# Verify installation
tuxcare-eportal-mcp --help

Option 2: NPX (No Installation Required)

# Run directly with npx
npx tuxcare-eportal-mcp --help

# Use in MCP configuration with npx
npx tuxcare-eportal-mcp --url https://your-eportal.com --auth-type basic --username admin --password secret

Option 3: GitHub Installation

# Install directly from GitHub
npm install -g github:Revmagi/tuxcare-eportal-mcp

# Or clone and install locally
git clone https://github.com/Revmagi/tuxcare-eportal-mcp.git
cd tuxcare-eportal-mcp
npm install
npm run build
npm link

Configuration Guide

Configuration Methods

You can configure the MCP server in three ways:

Configuration File (recommended for permanent setups)
Command Line Arguments (good for testing and Claude Code)
Environment Variables (for containerized deployments)

Method 1: Configuration File

Create a configuration file in JSON format:

Basic Authentication Example (config.json):

{
  "eportal_url": "https://your-eportal.com",
  "auth": {
    "type": "basic",
    "username": "admin",
    "password": "your-password"
  }
}

API Key Authentication Example (config.json):

{
  "eportal_url": "https://your-eportal.com",
  "auth": {
    "type": "api_key",
    "api_key": "your-api-key",
    "header_name": "X-Api-Key"
  }
}

Configuration File Locations

The server looks for configuration files in the following order:

Specified path: --config /path/to/config.json
Current directory: ./config.json
Home directory: ~/.tuxcare-eportal-mcp/config.json
System directory: /etc/tuxcare-eportal-mcp/config.json

Method 2: Command Line Arguments

You can pass all configuration via command line arguments:

# Basic authentication
tuxcare-eportal-mcp \
  --url https://your-eportal.com \
  --auth-type basic \
  --username admin \
  --password your-password

# API key authentication
tuxcare-eportal-mcp \
  --url https://your-eportal.com \
  --auth-type api_key \
  --api-key your-api-key \
  --header-name X-Api-Key

Method 3: Environment Variables

Set environment variables for secure configuration:

export TUXCARE_EPORTAL_URL="https://your-eportal.com"
export TUXCARE_AUTH_TYPE="basic"
export TUXCARE_USERNAME="admin"
export TUXCARE_PASSWORD="your-password"

# Or for API key
export TUXCARE_AUTH_TYPE="api_key"
export TUXCARE_API_KEY="your-api-key"
export TUXCARE_HEADER_NAME="X-Api-Key"

MCP Client Configuration

Claude Code Configuration

Method 1: Using Configuration File

Create a config file in your project directory:

{
  "eportal_url": "https://your-eportal.com",
  "auth": {
    "type": "basic",
    "username": "admin",
    "password": "your-password"
  }
}

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": ["tuxcare-eportal-mcp", "--config", "./config.json"]
    }
  }
}

Method 2: Using Command Line Arguments (No Config File)

Basic Authentication:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": [
        "tuxcare-eportal-mcp@1.0.4",
        "--url", "https://your-eportal.com",
        "--auth-type", "basic",
        "--username", "admin",
        "--password", "your-password"
      ]
    }
  }
}

API Key Authentication:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": [
        "tuxcare-eportal-mcp@1.0.4",
        "--url", "https://your-eportal.com",
        "--auth-type", "api_key",
        "--api-key", "your-api-key"
      ]
    }
  }
}

API Key with Custom Header:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": [
        "tuxcare-eportal-mcp@1.0.4",
        "--url", "https://your-eportal.com",
        "--auth-type", "api_key",
        "--api-key", "your-api-key",
        "--header-name", "X-API-Key"
      ]
    }
  }
}

Method 3: Using Environment Variables (Most Secure)

Basic Authentication:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": ["tuxcare-eportal-mcp@1.0.4"],
      "env": {
        "TUXCARE_EPORTAL_URL": "https://your-eportal.com",
        "TUXCARE_AUTH_TYPE": "basic",
        "TUXCARE_USERNAME": "admin",
        "TUXCARE_PASSWORD": "your-password"
      }
    }
  }
}

API Key Authentication:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": ["tuxcare-eportal-mcp@1.0.4"],
      "env": {
        "TUXCARE_EPORTAL_URL": "https://your-eportal.com",
        "TUXCARE_AUTH_TYPE": "api_key",
        "TUXCARE_API_KEY": "your-api-key"
      }
    }
  }
}

API Key with Custom Header:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": ["tuxcare-eportal-mcp@1.0.4"],
      "env": {
        "TUXCARE_EPORTAL_URL": "https://your-eportal.com",
        "TUXCARE_AUTH_TYPE": "api_key",
        "TUXCARE_API_KEY": "your-api-key",
        "TUXCARE_HEADER_NAME": "X-API-Key"
      }
    }
  }
}

Continue.dev Configuration

Add to your continue.json:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": ["tuxcare-eportal-mcp", "--config", "./config.json"]
    }
  }
}

Cline Configuration

Add to your MCP settings:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "tuxcare-eportal-mcp",
      "args": [
        "--url", "https://your-eportal.com",
        "--auth-type", "basic",
        "--username", "admin",
        "--password", "your-password"
      ]
    }
  }
}

Generic MCP Client Configuration

For any MCP client, use this format:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "tuxcare-eportal-mcp",
      "args": ["--config", "/path/to/config.json"]
    }
  }
}

Configuration Setup Commands

Quick Setup Command

Generate a configuration file interactively:

# Create config file with prompts
npx tuxcare-eportal-mcp --setup

# Create config file with basic auth
npx tuxcare-eportal-mcp --setup --url https://your-eportal.com --auth-type basic

# Create config file with API key
npx tuxcare-eportal-mcp --setup --url https://your-eportal.com --auth-type api_key

Test Configuration

Verify your configuration works:

# Test with config file
tuxcare-eportal-mcp --config ./config.json --test

# Test with command line args
tuxcare-eportal-mcp --url https://your-eportal.com --auth-type basic --username admin --password secret --test

Available Tools

Server Management

list_servers: List servers with filtering options
register_host: Register a new host
unregister_host: Unregister a host by hostname, IP, or server ID
bulk_unregister_hosts: Bulk unregister inactive hosts
set_server_tags: Set tags for a server

Feed Management

list_feeds: List all feeds
create_feed: Create or modify a feed
delete_feed: Delete a feed

Key Management

list_keys: List registration keys
create_key: Create or modify a registration key
delete_key: Delete a registration key

Patchset Management

list_patchsets: List patchsets for a feed and product
manage_patchsets: Enable, disable, or manage patchset deployments

User Management

list_users: List all ePortal users

Tool Usage Examples

List Servers

// List all servers
await callTool("list_servers", {});

// List servers with filtering
await callTool("list_servers", {
  hostname: "web%",
  tag: "env:production",
  limit: 50
});

// Get server count only
await callTool("list_servers", {
  only_count: true
});

Register Host

await callTool("register_host", {
  key: "production-key",
  hostname: "web-server-01"
});

Manage Patchsets

// Enable a patchset
await callTool("manage_patchsets", {
  patchset: "K20240101_01",
  feed: ["main", "staging"],
  action: "enable",
  product: "kernel"
});

// Enable all patchsets up to a specific one
await callTool("manage_patchsets", {
  patchset: "K20240101_01",
  feed: ["main"],
  action: "enable-upto",
  product: "kernel"
});

Set Server Tags

await callTool("set_server_tags", {
  server_id: "abc123",
  tags: "env:production;team:platform;ubuntu"
});

Authentication

Basic Authentication

{
  "auth": {
    "type": "basic",
    "username": "your-username",
    "password": "your-password"
  }
}

API Key Authentication

{
  "auth": {
    "type": "api_key",
    "api_key": "your-api-key",
    "header_name": "X-Api-Key"
  }
}

Security Best Practices

Never commit credentials to version control
Use environment variables for sensitive data
Restrict file permissions on config files: chmod 600 config.json
Use API keys instead of passwords when possible
Rotate credentials regularly
Use HTTPS for all ePortal connections

Troubleshooting

Common Issues

Connection Errors

# Test connection
curl -v https://your-eportal.com/api/v1/servers

# Check DNS resolution
nslookup your-eportal.com

Authentication Failures

# Test basic auth
curl -u username:password https://your-eportal.com/api/v1/servers

# Test API key
curl -H "X-Api-Key: your-key" https://your-eportal.com/api/v1/servers

Configuration Issues

# Validate configuration file
npx tuxcare-eportal-mcp --config ./config.json --validate

# Show current configuration
npx tuxcare-eportal-mcp --config ./config.json --show-config

Debug Mode

Enable debug logging:

# Debug mode
DEBUG=tuxcare:* tuxcare-eportal-mcp --config ./config.json

# Verbose output
tuxcare-eportal-mcp --config ./config.json --verbose

Error Handling

The server provides comprehensive error handling:

Authentication errors: Clear messages for credential issues
API errors: Detailed error messages from the ePortal API
Validation errors: Input validation with helpful error messages
Network errors: Timeout and connection error handling

Development

Setup

git clone https://github.com/Revmagi/tuxcare-eportal-mcp.git
cd tuxcare-eportal-mcp
npm install

Build

npm run build

Development Mode

npm run dev

Testing

npm test

Linting

npm run lint
npm run lint:fix

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Run linting and tests
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

Issues: GitHub Issues
Documentation: TuxCare Documentation
ePortal API: See the ePortal API documentation for detailed API reference

Version History

1.0.0: Initial release with full ePortal API support