MCP Server
Your infrastructure,
meet AI.
Connect HostAtlas to Claude Code, Cursor, Windsurf, and any MCP-compatible AI assistant. Manage servers, check alerts, tail logs, and run recipes — all through natural language. No dashboards required.
29
Tools
3
Resources
0
Dependencies
npx
Install & run
Model Context Protocol
What is MCP?
The Model Context Protocol (MCP) is an open standard created by Anthropic for connecting AI assistants to external tools and data sources. Think of it as a universal adapter between large language models and the real world.
Instead of copying and pasting data into a chat window, MCP lets AI assistants directly query your systems, read your data, and take actions on your behalf — with your explicit permission every step of the way.
HostAtlas is one of the first infrastructure platforms with native MCP support. Our MCP server exposes 29 tools and 3 resources that give AI assistants deep, real-time access to your entire infrastructure — not just the HostAtlas dashboard, but directly into each server.
How it works
You ask a question
"Are any of my servers running low on disk space?"
AI calls MCP tools
The assistant calls list_servers and list_alerts automatically.
You get a clear answer
"web-03 is at 91% disk usage on /dev/sda1. There's an active alert for it. Want me to check the logs?"
What's new — Direct server access
Read configs. Check logs. Diagnose issues. From your AI.
The HostAtlas MCP server no longer just controls the platform — it now lets your AI assistant directly read data from each server. Configs, firewall rules, live metrics, processes, cron jobs, Docker containers, network connections, and logs. All via the HostAtlas agent already running on your boxes.
No SSH keys to distribute. No remote shell to expose. No new agent to install. The AI asks, the platform routes the question to the agent, the agent reads and returns. Every call is authenticated, scoped by the API key's permission level, and optionally restricted to a specific allowlist of servers.
Read configs
nginx.conf, apache2.conf, my.cnf, redis.conf, php.ini, and any other service config the agent has discovered.
Read firewall
UFW rules, Fail2Ban jails, currently banned IPs, and recent ban events — all in one structured response.
Read metrics
Live CPU, RAM, disk, load averages, network throughput, and plugin-reported metrics (MySQL, Redis, queue depth, etc.).
Read processes
Running services, supervisor processes, detected versions (nginx, php, mysql, node), and listening ports.
Read cron jobs
Every discovered cron schedule on the server — system crontabs, per-user crontabs, and /etc/cron.d entries with owner and command.
Read logs
syslog, auth.log, nginx access/error logs, MySQL error log, custom app logs — anything the agent can see on disk.
Permissions & scope
You decide what the AI can see — and touch.
Every API key now has an MCP permission level that gates what it can do through the MCP server. Combined with per-server allowlists, you get precise control over AI access without giving up the convenience of natural-language ops.
New keys default to read — the AI can list, inspect, and analyze, but cannot restart services, run recipes, or change configuration. Upgrade to write only for the workflows that need it.
Best practice: Create a dedicated “AI Assistant” API key with read permission and an allowlist limited to the specific servers you want the assistant to analyze. Keep your human admin keys separate.
none No MCP access
The API key works for the REST API and CLI, but the MCP server will reject every tool call. Use this for keys embedded in CI, webhooks, or other non-AI integrations.
read Read-only access (default)
The AI can list servers, read configs, tail logs, inspect metrics — everything needed for diagnostics. But it cannot restart services, run recipes, or modify firewall rules.
write Read & execute
Everything in read, plus the ability to restart services, run recipes, acknowledge alerts, create incidents, and toggle attack mode.
Per-server allowlist
Restrict each API key to a specific set of servers. The MCP server will refuse to read configs or logs from any server not in the allowlist — even with write permission.
Setup
Connected in under a minute.
Choose your AI assistant and add the HostAtlas MCP server. Authentication is automatic if you've already logged in via the CLI.
Create an API key with MCP permissions
In the HostAtlas dashboard, go to Settings → API Keys and click Create key. The create-key modal now includes an MCP permission selector:
read— list & inspect only (default, recommended for AI keys)write— read plus restart, run recipes, acknowledge alertsnone— disables MCP entirely for this key
Optionally restrict the key to a subset of servers via the Server allowlist selector in the same modal.
Claude Code
That's it. Claude Code will now have access to all 29 HostAtlas tools — scoped to whatever your API key allows.
Cursor / Windsurf
Add this to your .cursor/mcp.json or .windsurf/mcp.json:
Authentication
The MCP server automatically reads credentials from the CLI config file. If you've logged in with hostatlas login, you're already authenticated:
Alternatively, set HOSTATLAS_API_URL and HOSTATLAS_API_KEY environment variables.
Tools
29 tools. Full infrastructure control.
Every tool is available to any MCP-compatible AI assistant. The assistant decides which tools to call based on your natural language request. Tools are gated by the API key's MCP permission level.
Server Access
Read-only 8 tools — direct reads from the HostAtlas agentread_server_configs nginx.conf, apache2.conf, my.cnf, redis.conf, php.ini
read_server_firewall UFW rules, Fail2Ban jails, banned IPs, ban events
read_server_metrics CPU, RAM, disk, load, network, plugin metrics
read_server_processes Running services, supervisor, versions, ports
read_server_cron_jobs System + per-user crontabs, users, commands
read_server_containers Docker containers, state, ports, images
read_server_connections Active network connections, listening sockets
read_server_logs syslog, auth.log, nginx, mysql, custom app logs
Platform control
Platform
get_status Platform health, server counts, alert summary Servers
list_servers All servers with status and resource usage get_server Detailed info for a specific server restart_service Restart nginx, mysql, php-fpm, etc. run_audit Security and configuration audit Alerts
list_alerts All currently firing alerts acknowledge_alert Mark an alert as acknowledged Incidents
list_incidents All incidents, open and resolved create_incident Create an incident with severity level Domains
list_domains All domains across all servers Uptime
list_monitors All uptime monitors and their status list_heartbeats All heartbeat monitors and status Logs
request_logs Tail log files from any server in real time Recipes
list_recipes All available automation recipes run_recipe Execute a recipe on a target server Backups
list_backup_paths Configured backup watch paths update_backup_paths Update backup watch paths list_offsite_backups All offsite backups, filterable by server restore_offsite_backup Restore a backup to a target server Attack Mode
get_attack_mode_status Current attack mode state activate_attack_mode Enable aggressive DDoS protection deactivate_attack_mode Return to normal protection levels Resources
Always-on context for your AI.
MCP resources provide background context to the AI assistant without requiring explicit tool calls. The assistant can read these automatically to understand the current state of your infrastructure before you even ask a question.
hostatlas://status Platform Status
Real-time platform health including server counts, active alerts, and system-wide metrics. The AI reads this first to understand the big picture.
hostatlas://servers Server List
Complete inventory of all monitored servers with their names, IPs, operating systems, and current status. The AI uses this to resolve server names to UUIDs.
hostatlas://alerts Active Alerts
All currently firing alerts across your fleet. The AI uses this to proactively surface issues and correlate problems across servers.
Examples
Infrastructure ops in plain English.
Real conversations with real tools. No scripts, no YAML, no clicking through dashboards.
Fleet overview
"How are my servers doing?"
Called: get_status, list_alerts
Your fleet looks mostly healthy. 12 servers online, 0 offline. However, there are 2 active alerts:
- web-03 — Disk usage at 91% on /dev/sda1 (critical threshold: 90%)
- db-01 — MySQL replication lag at 47 seconds (warning threshold: 30s)
Want me to dig into either of these?
Service restart
"Restart nginx on prod-01"
Called: list_servers → restart_service(server_uuid, "nginx")
Done. Nginx on prod-01 (Ubuntu 22.04, 10.0.1.12) has been restarted successfully. The service is back up and responding on ports 80 and 443.
Log tailing
"Show me the last nginx errors on web-02"
Called: list_servers → request_logs(server_uuid, "/var/log/nginx/error.log", 50)
Found 3 errors in the last 50 lines of /var/log/nginx/error.log on web-02:
Looks like the PHP-FPM upstream is timing out and eventually refusing connections. Want me to restart PHP-FPM on web-02?
Attack detection
"Are we under attack?"
Called: list_servers → get_attack_mode_status (x3 for critical servers)
I checked attack mode status on your 3 production servers:
- prod-01 — Attack mode: inactive, no anomalies
- prod-02 — Attack mode: inactive, no anomalies
- prod-03 — Attack mode: inactive, no anomalies
All clear. No attack mode triggers and no unusual activity detected. Want me to activate attack mode on any of these as a precaution?
Recipe execution
"Deploy the Laravel app on staging"
Called: list_recipes → list_servers → run_recipe(recipe_uuid, server_uuid)
Found the "Laravel Deploy" recipe and the staging-01 server. Running now...
Recipe completed successfully in 34 seconds. The deployment pulled the latest code from main, ran migrations, cleared the cache, and restarted the queue workers.
Deep-dive diagnostics
New"Why is nginx slow on web-prod-01?"
Called: read_server_metrics → read_server_configs → read_server_logs(nginx/error.log)
I pulled metrics, the nginx config, and the error log from web-prod-01. Three things stand out:
- Load average is 8.4 on a 4-core box — you're CPU-bound.
worker_processesis set to2in nginx.conf — should beautoto use all 4 cores.- PHP-FPM upstream is timing out — 14
upstream timed outerrors in the last hour.
Raise worker_processes, bump pm.max_children in PHP-FPM, and it should recover. Want me to run the nginx-tune recipe?
Cron audit
New"Show me all cron jobs running as root on db-prod-01"
Called: read_server_cron_jobs(server_uuid)
Four cron jobs run as root on db-prod-01:
The weekly apt-get upgrade at 4am Sunday is worth a look — unattended package upgrades on a DB host can cause surprises. Want me to pull it out into a recipe with better logging?
Firewall state
New"What IPs are currently banned on web-prod-01?"
Called: read_server_firewall(server_uuid)
Fail2Ban currently has 14 banned IPs across 3 jails on web-prod-01:
sshd— 9 IPs banned (7 from AS4134 China Telecom)nginx-http-auth— 3 IPs bannednginx-badbots— 2 IPs banned
Ban events in the last hour: 23. That's above baseline. Want me to check the auth.log for patterns or escalate to attack mode?
Security
Built with zero-trust in mind.
The MCP server inherits the same security model as the HostAtlas CLI. Your API key never leaves your machine and all communication happens over HTTPS with TLS 1.3.
Every tool call goes through the HostAtlas API with full authentication and authorization. The MCP server itself stores nothing — it's a stateless bridge between your AI assistant and the HostAtlas platform.
API key authentication
Every request is authenticated with your personal API key. Scoped permissions ensure the MCP server can only access what you've authorized.
HTTPS only
All API communication is encrypted with TLS 1.3. No plaintext. No fallback. Certificate pinning on the client.
No credentials stored
The MCP server reads credentials from the CLI config file or environment variables. It never writes, caches, or logs your API key.
Config file permissions
The ~/.hostatlas/cli.json config file is created with 0600 permissions — readable only by the file owner.
npm Package
One package. Zero dependencies.
The HostAtlas MCP server is published on npm as @hostatlas/mcp-server. Use npx to run it directly without installing, or add it globally.
Run directly
Install globally
Package details
@hostatlas/mcp-server 1.0.0 Node.js 18+ MCP via stdio 0 (bundled) MIT Get started
Let AI handle your infrastructure ops.
Connect HostAtlas to your AI assistant in one command. 29 tools, 3 resources, zero configuration. Ask questions in natural language, get real answers backed by real data from your platform and directly from your servers — and take action without leaving your editor.
# Add to Claude Code
claude mcp add hostatlas -- npx @hostatlas/mcp-server
# Or run directly
npx @hostatlas/mcp-server