deploy-observability

Deploy Alibaba Cloud Observability MCP Server

Overview

This skill guides users through deploying and managing the Alibaba Cloud Observability MCP Server. It covers:

First-time deployment — clone, build, configure credentials, start, generate agent config
Docker deployment — containerized setup for servers
Project update — pull latest code, detect changes, rebuild, report new tools

The server provides 60+ tools for Alibaba Cloud Log Service (SLS), CloudMonitor (CMS), and AI-powered observability. It can run locally (stdio) or as a remote HTTP service (sse/streamable-http).

Phase 0: Pre-flight Checks

Before starting any deployment, run these checks to understand the environment:

Detect Existing Installation

# Check if already installed in common locations
for dir in ~/alibabacloud-observability-mcp-server ~/.alibabacloud-observability-mcp-server /opt/alibabacloud-observability-mcp-server; do
  if [ -d "$dir" ] && [ -f "$dir/bin/alibabacloud-observability-mcp-server" ]; then
    echo "Found installation at: $dir"
    "$dir/bin/alibabacloud-observability-mcp-server" version
  fi
done

If an existing installation is found, ask the user:

An existing installation was detected. Do you want to update? Or perform a fresh installation to another location?

Check Go Environment

go version 2>/dev/null && echo "Go OK" || echo "Go NOT FOUND"

If Go is not installed:

Go is not installed (requires >= 1.23). Please go to https://go.dev/dl/ to download and install, or use a package manager:

macOS: brew install go

Ubuntu/Debian: sudo apt install golang-go

CentOS: sudo yum install golang

Check Network

curl -s --connect-timeout 5 https://github.com > /dev/null && echo "GitHub OK" || echo "GitHub UNREACHABLE"

If GitHub is unreachable (common in China):

GitHub is inaccessible. Please check your network connection, or use a mirror site:

git clone https://ghproxy.com/https://github.com/aliyun/alibabacloud-observability-mcp-server.git

Phase 1: First-Time Deployment

Ask the user where to install (default: ~/Projects/alibabacloud-observability-mcp-server).

There are two ways to get the binary. Let the user choose:

Step 1.1a — Download Pre-built Binary (fastest, recommended)

# macOS arm64 (M1/M2/M3/M4)
wget https://github.com/aliyun/alibabacloud-observability-mcp-server/releases/latest/download/alibabacloud-observability-mcp-server-darwin-arm64.tar.gz
tar -xzf alibabacloud-observability-mcp-server-darwin-arm64.tar.gz
cd alibabacloud-observability-mcp-server

# macOS amd64 (Intel)
wget https://github.com/aliyun/alibabacloud-observability-mcp-server/releases/latest/download/alibabacloud-observability-mcp-server-darwin-amd64.tar.gz
tar -xzf alibabacloud-observability-mcp-server-darwin-amd64.tar.gz
cd alibabacloud-observability-mcp-server

⚠️ macOS "Cannot verify developer" prompt: On first run, macOS may block execution and show a "Cannot verify developer" prompt. How to resolve:

System Settings → Privacy & Security → find the blocked file → click "Allow Anyway"
Or run in the terminal:xattr -d com.apple.quarantine bin/alibabacloud-observability-mcp-server

Step 1.1b — Clone and Build from Source

git clone https://github.com/aliyun/alibabacloud-observability-mcp-server.git <install_path>
cd <install_path>

Optional: Pin to a specific release version:

# List available versions
git tag -l 'go/v*'

# Checkout a specific version
git checkout go/v0.1.8

Build:

go mod tidy
make build
chmod +x bin/alibabacloud-observability-mcp-server

Verify:

./bin/alibabacloud-observability-mcp-server version

If make build fails:

Check Go version: go version (needs >= 1.23)
Try go mod download first
Check for C compiler issues (should not be needed — pure Go)

Step 1.2 — Configure Credentials

cp .env.example .env

Present the credential table to the user:

Environment Variable	Description	Required
`ALIBABA_CLOUD_ACCESS_KEY_ID`	Alibaba Cloud AccessKey ID	Yes*
`ALIBABA_CLOUD_ACCESS_KEY_SECRET`	Alibaba Cloud AccessKey Secret	Yes*
`ALIBABA_CLOUD_REGION`	Default region	No (defaults to cn-hangzhou)
`ALIBABA_CLOUD_WORKSPACE`	Default workspace	No
`ALIBABA_CLOUD_SECURITY_TOKEN`	STS temporary credentials	No

* If running on ECS/FC with a RAM Role configured, you can skip the AccessKey; the service will automatically use the default credential chain.

Tell the user:

Please edit the .env file and fill in your Alibaba Cloud AccessKey. How to obtain:https://ram.console.aliyun.com/manage/ak

Wait for the user to confirm they've filled in the credentials.

Step 1.3 — Choose Transport Mode

Ask the user to choose:

Mode	Description	Use Case
stdio	Standard input/output	IDE integration (Cursor / Claude Code, etc.), for local use
sse	Server-Sent Events	Remote HTTP access
streamable-http	HTTP streaming transport	Remote HTTP access (recommended for production)

If stdio: Tell the user:

stdio mode is usually started automatically by the IDE and does not need to be run manually. Skip directly to Step 1.4 to generate the configuration.

If sse or streamable-http:

Edit config.yaml:

server:
  transport: streamable-http  # 或 sse
  host: 0.0.0.0
  port: 8180

Start the server:

./bin/alibabacloud-observability-mcp-server start --config config.yaml

Verify:

curl http://localhost:8180/health

If health check fails:

Check logs (stderr output)
Verify .env has valid credentials
Check if port 8180 is already in use: lsof -i :8180

Step 1.4 — Generate Agent Integration Config

Ask the user which AI agent they want to connect to, then generate the config.

For streamable-http / sse mode (remote server):

{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "url": "http://<server_ip>:8180"
    }
  }
}

For stdio mode (local):

{
  "mcpServers": {
    "alibaba_cloud_observability": {
      "command": "<install_path>/bin/alibabacloud-observability-mcp-server",
      "args": ["start", "--stdio"],
      "env": {
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "<your_access_key_id>",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "<your_access_key_secret>"
      }
    }
  }
}

Tell the user where to paste the config:

Agent	Configuration file path
Cursor	Settings → MCP → Add Server (UI operation)
Claude Code	`~/.claude/settings.json` or project `.claude/settings.json`
Kiro	Settings → MCP Servers (UI operation)
Windsurf	Settings → MCP Configuration
Cline	`.cline/mcp_settings.json` in the project root directory

Paste the above JSON configuration into your AI Agent. If it is a remote server, replace <server_ip> with the actual IP address.

Step 1.5 — Paid Tools Warning

IMPORTANT: Inform the user about paid tools before they finish:

⚠️ Paid tool reminder

The following AI intelligent tools incur STAROps charges on each invocation:

sls_text_to_sql — Natural language to SQL

sls_text_to_spl — Natural language to SPL

sls_sop — SLS intelligent O&M assistant

cms_natural_language_query — Natural language data query

If you do not need AI capabilities, you can, in the config.yaml of the enabled_tools , enable only free tools to avoid unexpected charges.

Billing details:https://www.aliyun.com/price/product#/starops/detail

Phase 1b: Docker Deployment (alternative)

For users who prefer containerized deployment (servers, CI/CD, etc.):

Build and Run with Docker

# Build image
docker build -t observability-mcp-server .

# Run with environment variables
docker run -d \
  --name observability-mcp \
  -p 8180:8180 \
  -e ALIBABA_CLOUD_ACCESS_KEY_ID=<your_key> \
  -e ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your_secret> \
  -e ALIBABA_CLOUD_REGION=cn-hangzhou \
  observability-mcp-server

Or use Docker Compose

# Create .env file with credentials
cat > .env << 'EOF'
ALIBABA_CLOUD_ACCESS_KEY_ID=<your_key>
ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your_secret>
ALIBABA_CLOUD_REGION=cn-hangzhou
EOF

# Start
docker-compose up -d

Verify:

curl http://localhost:8180/health

After Docker deployment, generate the agent config using http://<server_ip>:8180 as the URL (same as Step 1.5).

Phase 2: Project Update

When the user wants to update an existing deployment:

Step 2.1 — Locate Installation

If the user doesn't know the install path:

# Search for existing installations
find ~ -maxdepth 3 -name "alibabacloud-observability-mcp-server" -type d 2>/dev/null

Step 2.2 — Record Current State

cd <install_path>

# Save current version and tool list
./bin/alibabacloud-observability-mcp-server version > /tmp/version_before.txt 2>/dev/null || true
./bin/alibabacloud-observability-mcp-server tools > /tmp/tools_before.txt 2>/dev/null || true

Step 2.3 — Pull Latest Code

git pull origin master
go mod tidy

Step 2.4 — Detect Changes and Report

Run these checks and present results clearly:

1. Dependency changes:

git diff HEAD@{1} --name-only 2>/dev/null | grep -E 'go\.(mod|sum)' && echo "DEPENDENCIES CHANGED" || echo "No dependency changes"

2. Config changes:

git diff HEAD@{1} -- config.yaml .env.example 2>/dev/null

If .env.example changed, show new variables and ask the user to update .env.

3. Rebuild and compare tools:

make build
chmod +x bin/alibabacloud-observability-mcp-server

# Compare tool lists
diff /tmp/tools_before.txt /tmp/tools_after.txt 2>/dev/null || true

Step 2.5 — Report Summary

Present a clear summary:

📦 更新完成

版本: <old_version> → <new_version>
依赖: 有变更 / 无变更
配置: 需要更新 .env / 无需更新
工具变更:
  ✅ 新增 N 个工具: tool_a, tool_b, ...
  ❌ 移除 N 个工具: tool_x, ...
服务状态: 需要手动重启 / 已在运行

If the server was running, restart with the same transport mode.

Troubleshooting

Issue	Solution
`command not found: go`	Install Go >= 1.23: https://go.dev/dl/
`credentials not configured`	Edit `.env`, fill in the AccessKey ID and Secret
`config file not found`	Ensure `config.yaml` exists in the project directory
`address already in use`	`lsof -i :8180` to view the occupying process,`kill -9 <PID>` or change the port
Health check returns an error	Check the stderr logs and verify that the credentials in `.env` are correct
`git clone` timeout	Domestic users try mirror: `https://ghproxy.com/https://github.com/...`
`go mod tidy` failed	Check network connection, set GOPROXY: `export GOPROXY=https://goproxy.cn,direct`
Build error `undefined` occurred	`go mod tidy` re-download dependencies
`permission denied`	`chmod +x bin/alibabacloud-observability-mcp-server`
Paid tools incur unexpected charges	In `config.yaml` use `enabled_tools` enable only free tools

About this skill

Overview

Phase 0: Pre-flight Checks

Detect Existing Installation

Check Go Environment

Check Network

Phase 1: First-Time Deployment

Step 1.1a — Download Pre-built Binary (fastest, recommended)

Step 1.1b — Clone and Build from Source

Step 1.2 — Configure Credentials

Step 1.3 — Choose Transport Mode

Step 1.4 — Generate Agent Integration Config

Step 1.5 — Paid Tools Warning

Phase 1b: Docker Deployment (alternative)

Build and Run with Docker

Or use Docker Compose

Phase 2: Project Update

Step 2.1 — Locate Installation

Step 2.2 — Record Current State

Step 2.3 — Pull Latest Code

Step 2.4 — Detect Changes and Report

Step 2.5 — Report Summary

Troubleshooting