Codex용 Atera MCP

공식 Atera REST API를 위한 독립형 MCP 서버입니다.

현재 vertical slice에는 다음이 포함됩니다:

• MCP stdio transport 및 legacy/modern 프로토콜 협상;

• atera_health_check 및 atera_capabilities;

• Customers, Agents, Tickets 및 Alerts 읽기;

• legacy X-API-KEY 또는 Bearer JWT 자동 선택, 수동 override 지원;

• timeout, cancellation, rate limiting, Retry-After 및 안전한 GET 재시도;

• 정규화된 오류 및 관리되는 변경 정책(기본적으로 쓰기와 삭제가 활성화됨).

모든 Atera endpoint의 전체 카탈로그는 최신 OpenAPI를 가져온 후 추가됩니다. 지침: docs/OPENAPI_IMPORT.md. 도메인별 Reference baseline: REFERENCE_COVERAGE.md.

로컬 tenant export는 이미 검증되었습니다: OpenAPI 3.0.4, 81개 paths 및 136개 operations(69 GET, 35 POST, 19 PUT, 13 DELETE). 파일은 openapi-private/에 있으며 의도적으로 git에서 제외됩니다. 서버는 시작 시 이 operations를 추가 MCP tools로 게시합니다.

실행

npm install
npm run typecheck
npm test
npm run build
npm run openapi:validate -- openapi-private/atera-openapi.json

마지막 명령은 Codex를 재시작하기 전에 가져온 tenant 스키마를 확인합니다. 파일이 아직 없으면 명확한 진단과 함께 종료됩니다.

변수는 환경 변수로 설정합니다. 템플릿은 .env.example에 있습니다. 최소한 ATERA_API_TOKEN 또는 legacy ATERA_API_KEY가 필요합니다.

ATERA_API_TOKEN='…' npm start

시크릿을 git에 추가하지 말고 MCP tool 인수로 전달하지 마세요.

Related MCP server: Codex MCP Server

Codex 연결

Codex 구성에 로컬 서버를 추가합니다. macOS/Linux에서는 Node.js 경로를 which node 명령으로 확인하고, Windows에서는 where node를 사용합니다:

[mcp_servers.atera]
command = "/opt/homebrew/bin/node"
args = ["/Users/vardahei/Documents/atera-mcp/dist/src/index.js"]
startup_timeout_sec = 30

[mcp_servers.atera.env]
ATERA_API_TOKEN = "<Atera token>"
ATERA_BASE_URL = "https://api.atera.com/api/v3"
ATERA_AUTH_MODE = "bearer"
ATERA_OPENAPI_PATH = "/Users/vardahei/Documents/atera-mcp/openapi-private/atera-openapi.json"
ATERA_WRITE_ENABLED = "true"
ATERA_ENABLE_DESTRUCTIVE_OPERATIONS = "true"

쓰기 및 삭제는 기본적으로 활성화되어 있습니다. 해당 값을 false로 설정하면 로컬에서 비활성화할 수 있습니다. 기능은 여전히 Atera token 권한에 의해 제한됩니다.

직원이 GitHub에서 설치하기

직원은 지원되는 모든 OS에서 Codex에 다음과 같은 작업을 지시할 수 있습니다:

Установи Atera MCP из https://github.com/Oleksandr-Kliuiev/atera-mcp.
Определи мою ОС. На macOS/Linux выполни scripts/install-codex.sh, на Windows — scripts/install-codex.ps1.
Не запрашивай и не выводи мой Atera token в чат. После установки объясни, как добавить мой token локально в окружение MCP-сервера atera.

macOS/Linux에서는 로컬에서 실행할 수 있습니다:

git clone https://github.com/Oleksandr-Kliuiev/atera-mcp.git ~/.local/share/codex/atera-mcp
~/.local/share/codex/atera-mcp/scripts/install-codex.sh

Windows PowerShell의 경우:

$dir = Join-Path $HOME ".local\share\codex\atera-mcp"
git clone https://github.com/Oleksandr-Kliuiev/atera-mcp.git $dir
& "$dir\scripts\install-codex.ps1"

모든 OS의 요구 사항: Git, Node.js 20+ 및 설치된 Codex CLI. Windows에서 스크립트는 PowerShell에서 실행됩니다. 로컬 스크립트를 허용하지 않는 실행 정책이 있는 경우 powershell -ExecutionPolicy Bypass -File .\scripts\install-codex.ps1을 사용하세요.

설치 프로그램은 종속성을 설치하고, 서버를 빌드하며, stdio MCP를 Codex에 등록합니다. 각 직원은 자신의 ATERA_API_TOKEN만 추가합니다. 공용 token은 저장소에 없습니다. 기본적으로 쓰기 및 삭제가 활성화되어 있습니다. 필요한 경우 ATERA_WRITE_ENABLED=false 및 ATERA_ENABLE_DESTRUCTIVE_OPERATIONS=false를 통해 비활성화할 수 있습니다.