oitvoip-mcp

Oitvoip(호스팅 VoIP/UCaaS 리셀러 플랫폼, NetSapiens 기반 — API 호스트 패턴은 {tenant-pbx-host}/ns-api/)용 MCP 서버입니다. NetSapiens ns-api의 도메인, 리셀러, 장치, 가입자, CDR 메서드를 MCP 도구로 노출합니다.

명칭 참고: MSPbots 자체 통합은 "Oitvoip"으로 등록되어 있습니다(subjectCode=NS — NetSapiens의 약어). 기본 API와 모든 공식 문서는 "NetSapiens" / "ns-api"를 참조합니다. 이 MCP는 MSPbots 자체가 구성한 정확히 5개의 메서드를 다룹니다.

개요

• 무상태(Stateless) HTTP 서비스. 자격 증명은 절대 영구 저장되지 않습니다 — 각 요청은 헤더를 통해 자체 자격 증명을 제공하며, 해당 단일 요청의 수명 동안에만 사용됩니다.

• 동시 요청을 지원합니다. 요청별 자격 증명 격리는 전역/공유 클라이언트 인스턴스가 아닌 Python contextvars를 통해 수행됩니다.

• 진입점: POST /mcp(MCP 프로토콜) 및 GET /health(헬스 체크).

• 기본 포트: 8080(MCP_HTTP_PORT로 구성 가능).

Related MCP server: whmcs-mcp-server

인증

NetSapiens는 표준 OAuth2 password grant를 사용합니다:

POST https://{site}/ns-api/oauth2/token/
  grant_type=password&client_id=...&client_secret=...&username=...&password=...
-> {"access_token": "...", "expires_in": 3600, "token_type": "Bearer", ...}

결과 access_token은 1시간 동안 유효하지만, 이 서버는 MCP 요청 간에 캐시하지 않고 모든 단일 도구 호출 시 새로 인증합니다 — 아무것도 캐시되거나 영구 저장되지 않습니다. 그런 다음 모든 실제 ns-api 호출은 Authorization: Bearer <access_token>을 전송합니다.

헤더 인증 파라미터 설명

헤더가 누락되면 401을 반환합니다:

{
  "error": "Missing credentials",
  "message": "This server requires the X-Oitvoip-Site, X-Oitvoip-Client-Id, X-Oitvoip-Client-Secret, X-Oitvoip-Username, X-Oitvoip-Password headers",
  "required_headers": ["X-Oitvoip-Site", "X-Oitvoip-Client-Id", "X-Oitvoip-Client-Secret", "X-Oitvoip-Username", "X-Oitvoip-Password"],
  "optional_headers": []
}

잘못된 자격 증명 또는 인증되었지만 범위가 부족한 가입자 계정은 이 서버의 HTTP 수준 오류가 아닌 도구 수준 unauthorized 오류 봉투로 표시됩니다(메시지에는 공급업체 자체 세부 정보(예: Invalid Scope [APP001])가 포함됨) — 알려진 제한 사항 참조.

환경 변수

MCP 엔드포인트

• POST /mcp — MCP 프로토콜(streamable HTTP transport)

• GET /health — 헬스 체크, {"status": "ok"} 반환(순수 로컬 프로브, 공급업체 API 호출 안 함)

도구 목록

응답은 공급업체의 JSON(메서드에 따라 배열 또는 객체)이며, 간결하게 직렬화됩니다(들여쓰기 없음, ensure_ascii=False). 응답이 ~20,000자를 초과하면 가장 큰 목록 필드가 잘리고 결과에 truncated: true와 원래 개수가 포함되며, 무제한 blob을 반환하지 않습니다. 5개 도구 모두 읽기 전용(readOnlyHint)입니다 — 이 서비스에는 쓰기/삭제 도구가 없습니다.

오류 발생 시 도구는 예외를 발생시키는 대신 구조화된 JSON 오류 봉투를 반환합니다:

{"error": {"code": "unauthorized", "message": "...", "retryable": false}}

code는 not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error 중 하나입니다. retryable은 Agent가 안전하게 재시도할 수 있는지 여부를 나타냅니다(rate_limited 및 upstream_error의 경우 true).

테스트 예시

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Oitvoip-Site: pbx.example.com" \
  -H "X-Oitvoip-Client-Id: 58900.mspbot" \
  -H "X-Oitvoip-Client-Secret: <your-client-secret>" \
  -H "X-Oitvoip-Username: 1000@example" \
  -H "X-Oitvoip-Password: <your-password>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "oitvoip_get_subscribers",
      "arguments": {"domain": "example.58900.service"}
    }
  }'

실제 검증됨(2026-07-30) 실제 테넌트를 대상으로, 실행 중인 이 서버를 통해 5개 도구 모두 엔드투엔드로 호출됨: oitvoip_get_subscribers는 실제 가입자/내선 레코드를 반환했고, oitvoip_get_devices는 실제 등록된 SIP 장치(Polycom 엔드포인트, 실시간 등록 상태)를 반환했으며, oitvoip_get_cdr2는 지정된 날짜 범위에 대한 실제 통화 상세 기록을 반환했습니다. oitvoip_get_domains와 oitvoip_get_resellers는 API에 올바르게 도달하여 깔끔하고 예상된 401 Invalid Scope [APP001] 도구 수준 오류를 표시했습니다 — 제공된 테스트 자격 증명은 가입자 수준 계정(scope: "Office Manager")이며, 이 특정 NetSapiens 배포에서 도메인/리셀러 관리 권한을 보유하지 않습니다. 알려진 제한 사항 참조.

API 참조

• 공개, 로그인 불필요: https://api.ucaasnetwork.com/ns-api/apidoc/ (OAuth2, Domain, Reseller, Device, Subscriber, CDR 객체를 포함한 전체 ns-api 참조)

알려진 제한 사항

• 범위는 정확히 MSPbots가 구성한 5개 엔드포인트이며, 공급업체의 전체 API 표면이 아닙니다 — ns-api는 또한 Callqueue, Agent, Phonenumber, Dialplan, Contacts, Presence, Call Queue Report/Stat, 실시간 통화 제어 등을 다룹니다(공개 문서의 자체 객체 목록 기준). 이러한 항목은 여기서 범위를 벗어납니다.

• oitvoip_get_domains 및 oitvoip_get_resellers는 실제 데이터로 완전히 실시간 검증할 수 없었습니다 — 제공된 테스트 계정은 인증에 성공하지만(OAuth2 흐름과 이 구현이 올바르다는 것을 증명) 가입자 수준 "Office Manager" 역할로 범위가 지정되어 있으며, NetSapiens는 이 두 관리자 수준 객체에 대해 401 Invalid Scope [APP001]로 거부합니다. 이는 특정 테스트 계정의 자격 증명 권한 제한이며 이 서버의 버그가 아닙니다 — oitvoip_get_subscribers, oitvoip_get_devices, oitvoip_get_cdr2는 모두 동일한 로그인의 동일한 액세스 토큰을 사용하여 실제 데이터로 성공했습니다.

• CDR 날짜 범위 필드(start_date/end_date)는 검증되지 않은 문자열입니다 — MSPbots 자체 저장 사용과 일치하도록 YYYY-MM-DD HH:MM:SS 형식으로 공급업체에 그대로 전달됩니다. 클라이언트 측 날짜 구문 분석은 수행되지 않습니다.