Sisense 메타 관리 MCP 서버

⚠️ 실험적 프로젝트 공지

Sisense 필드 엔지니어링에서 기여한 커뮤니티 도구

이 프로젝트는 Sisense 필드 엔지니어링이 고객의 Sisense 기능 학습과 탐색을 돕기 위해 개발한 실험적 도구입니다. Sisense 핵심 제품 릴리스 수명 주기의 일부가 아니며, 일반 공급(GA) Sisense 기능과 동일한 검증, 지원, 인증 프로세스를 거치지 않습니다. "있는 그대로" 제공됩니다 — 지원 및 기여를 참조하세요.

PySisense SDK를 기반으로 Sisense 환경 운영을 AI 지원 도구로 노출하는 표준 준수 MCP 서버입니다: 거버넌스, 자산 및 사용자/그룹 관리, 수명 주기 작업, 상태 점검 — 차트 작성이나 분석 Q&A는 아닙니다.

모든 Sisense 사용자에게 작동합니다: 모든 도구 호출은 호출 사용자 자신의 Sisense 자격 증명으로 실행되므로 결과와 권한은 정확히 해당 사용자가 Sisense에서 보고 수행할 수 있는 것과 동일하며, Sisense API에 의해 기본적으로 강제됩니다.

도구만 제공하며 에이전트는 없습니다. Claude Desktop, Claude Code, claude.ai, Cursor — 모든 MCP 클라이언트는 자체 에이전트를 가져옵니다. 이 프로젝트는 약 100개의 선별된 도구(대시보드, 데이터 모델, 사용자/그룹, 폴더, 플러그인, 상태 점검 등)를 광고하고 실행합니다.

아키텍처

MCP 사양의 현대적 형태로, 두 개의 협력 서비스로 제공되며 두 개의 Docker 이미지(fes-auth, fes-mcp — 공유 레이어가 있는 단일 멀티 스테이지 Dockerfile에서 빌드)로 배포됩니다:

• fes-auth — 권한 부여 서버(AS). 누가 호출하는지에 관한 모든 것을 소유합니다: MCP 클라이언트용 OAuth 2.1(PKCE, 동적 클라이언트 등록, 검색), 브라우저 로그인 페이지, 발급된 각 MCP 토큰을 사용자의 Sisense 토큰에 매핑하는 자격 증명 저장소. 모든 도구 호출을 리소스 서버에 프록시하고 Sisense 자격 증명을 주입합니다.

• fes-mcp — 리소스 서버(RS). 상태 비저장, OAuth 인식 없음. 각 요청에서 주입된 자격 증명을 읽고 Sisense에 대해 검증(캐시됨)한 다음 해당 사용자로 해당 Sisense 인스턴스에 대해 도구를 실행합니다.

flowchart LR
    subgraph clients [MCP clients]
        C1[Claude Desktop]
        C2[Claude Code]
        C3[claude.ai / Cursor]
    end

    subgraph box [one host - docker compose]
        subgraph AS [fes-auth : authorization server]
            O[OAuth 2.1\nPKCE + DCR + discovery]
            L[/login page/]
            V[(vault\nMCP token → Sisense credential)]
            P[/mcp proxy\ninjects credential headers/]
        end
        subgraph RS [fes-mcp : resource server]
            T[Tool layer\nregistry-driven, ~100 tools]
            D[Dispatcher\nper-credential PySisense client]
        end
    end

    R[(tool registry JSON\nauto-generated from SDK)] -.defines.-> T

    C1 & C2 & C3 -- "MCP over HTTPS\nBearer <MCP token>" --> P
    C1 & C2 & C3 -. "browser: sign in once" .-> L
    P -- "Authorization: Bearer <Sisense token>\nX-Sisense-Url: <instance>\n(internal network only)" --> T
    T --> D
    D -- "REST, as the signed-in user" --> F[(Sisense Fusion Deployment)]

두 서비스 사이의 연결은 단지 두 개의 헤더와 401 계약뿐이므로 각 절반은 서로 인식하지 못한 채 진화하거나 교체될 수 있습니다. 두 서비스 사이에는 의도적으로 공유 비밀번호가 없습니다 — 신뢰는 내부 네트워크입니다(RS의 포트는 절대 게시되지 않음).

로그인 흐름(사용자가 경험하는 것)

각 사용자는 MCP 클라이언트에서 커넥터를 한 번 추가하고 URL에 자신의 Sisense 인스턴스를 지정합니다:

https://your-host/mcp?target=https://acme.sisense.com

sequenceDiagram
    participant U as User (browser)
    participant C as MCP client
    participant A as fes-auth
    participant S as Sisense

    C->>A: POST /mcp?target=<sisense url>  (no token)
    A-->>C: 401 + resource metadata URL (carries target)
    C->>A: discovery + client registration (RFC 7591)
    C->>U: open browser at A's /login
    Note over U,A: target present → instance fixed,<br/>only username/password asked<br/>(no target → domain field shown)
    U->>A: username/password (or API token for SSO)
    A->>S: POST /api/v1/authentication/login
    S-->>A: user's Sisense token (kept server-side, in the vault)
    A-->>C: authorization code → MCP access token (PKCE)
    Note over C,A: from here, silent — token refresh is automatic

클라이언트는 Sisense 자격 증명을 볼 수 없습니다. 서버는 비밀번호를 저장하지 않습니다(사용자의 토큰을 발급하는 데 한 번 사용된 후 폐기). SSO/MFA 인스턴스의 사용자는 개인 Sisense API 토큰을 붙여넣어 로그인합니다.

도구 호출(정상 상태)

sequenceDiagram
    participant C as MCP client
    participant A as fes-auth (proxy)
    participant R as fes-mcp (tools)
    participant S as Sisense (target)

    C->>A: POST /mcp  (Bearer <MCP token>)
    A->>A: validate token → vault → Sisense credential
    A->>R: same request + Authorization: Bearer <Sisense token><br/>+ X-Sisense-Url: <instance>
    R->>S: verify credential (TTL-cached) · SDK call as that user
    S-->>R: result (user's permissions, user in audit log)
    R-->>A: MCP response (streamed)
    A-->>C: MCP response (streamed)

자격 증명 수명 주기 및 자가 치유

• 리소스 서버는 FES_MCP_VERIFY_TTL초(기본 300) 후에 각 (인스턴스, 토큰) 쌍을 Sisense에 대해 다시 검증합니다. Sisense에서 취소된 토큰은 최대 해당 시간 내에 HTTP 401로 변환됩니다.

• fes-auth는 RS 401을 자격 증명 만료로 처리합니다: 저장소 항목을 삭제하고 MCP 클라이언트에 다시 도전하며, 클라이언트의 다음 동작은 로그인 흐름을 다시 실행하는 것입니다. 따라서 서버 측 취소는 수동 단계 없이 전파됩니다.

• 세션은 의도적으로 메모리 내에 있습니다(데이터베이스 없음): fes-auth를 다시 시작하면 모든 사용자가 로그아웃됩니다 — 각 사용자의 다음 호출에서 브라우저 로그인이 다시 나타납니다(?target=이 설정된 경우 사용자 이름/비밀번호만). fes-mcp를 다시 시작하는 것은 보이지 않습니다: 상태를 보유하지 않습니다.

배포(docker compose)

docker compose up --build

이것은 두 이미지를 빌드하고(docker build --target fes-auth|fes-mcp) :8200에서 fes-auth만 게시합니다. fes-mcp는 내부에 유지됩니다. 앞에서 TLS를 종료하고(ALB / nginx / Caddy) — MCP 클라이언트는 OAuth에 HTTPS를 요구합니다 — FES_MCP_PUBLIC_URL을 해당 공개 URL로 설정합니다:

FES_MCP_PUBLIC_URL=https://your-host.example.com docker compose up -d --build

그런 다음 사용자는 https://your-host.example.com/mcp?target=https://their-instance.sisense.com을 사용자 지정 커넥터로 추가합니다. ?target= 부분은 선택 사항입니다 — 없으면 로그인 페이지에서 세 번째 필드로 Sisense URL을 묻습니다.

fes-auth의 엔드포인트: /mcp(프록시된 MCP), /login, /.well-known/* + /authorize + /token + /register(OAuth 2.1), /(상태), /healthz. 강화 포함: IP별 로그인 속도 제한, CSRF 보호 로그인 양식, 요청 ID가 있는 액세스 로그.

빠른 시작(로컬 개발)

Python 3.11+ 및 uv 필요. 로컬 개발은 AS를 완전히 건너뜁니다: stdio 전송은 기본적으로 env 인증을 사용합니다 — .env의 단일 자격 증명으로 모든 것이 사용자로 실행됩니다.

uv sync
cp .env.example .env   # set SISENSE_DOMAIN / SISENSE_TOKEN
uv run fes-mcp         # stdio transport

MCP 클라이언트 구성(예: claude_desktop_config.json):

{
  "mcpServers": {
    "sisense": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/fes_mcp", "fes-mcp"]
    }
  }
}

Docker 없이 로컬에서 전체 분할을 실행하려면:

FES_MCP_TRANSPORT=http uv run fes-mcp &                 # RS on :8200 (upstream auth)
FES_MCP_PORT=8300 FES_MCP_RS_URL=http://127.0.0.1:8200 uv run fes-auth
# connector: http://127.0.0.1:8300/mcp?target=https://your.sisense.com

레이아웃

• src/fes_mcp/ — settings(환경 구성) · registry(로드/필터) · dispatcher(자격 증명별 SDK 디스패치) · upstream(RS 자격 증명 검증) · auth(OAuth 공급자 + 로그인 페이지) · authserver(fes-auth 서비스 + 프록시) · middleware(액세스 로그) · server(FastMCP 어셈블리)

• config/tools.registry.with_examples.json — 자동 생성된 도구 레지스트리. 절대 수동으로 작성하지 마십시오. PySisense가 업데이트되면 ./refresh_registry.sh로 다시 생성하십시오.

• config/allowlist.txt — 선별된 도구 표면, 줄당 하나의 도구. 줄을 삭제/주석 처리하여 도구를 제거합니다. 나열되지 않은 도구는 절대 노출되지 않으므로 레지스트리 새로 고침이 표면을 조용히 확장할 수 없습니다. (마이그레이션 도구는 의도적으로 나열되지 않습니다 — 이 서버가 모델링하지 않는 이중 인스턴스 연결이 필요합니다.)

• 변경 도구는 FES_MCP_ALLOW_MUTATIONS=true 뒤에 게이트됩니다 — 전체 변경 안전 장치에 대해서는 보안을 참조하세요.

기술 및 보안 고려 사항

자격 증명 처리

MCP 클라이언트는 Sisense 자격 증명을 볼 수 없으며 서버는 비밀번호를 저장하지 않습니다 — 비밀번호는 Sisense 로그인 API에 대해 한 번 사용되어 사용자 자신의 토큰을 발급한 후 폐기됩니다. Sisense 토큰은 fes-auth의 메모리 내 저장소에 있으며 MCP 액세스 토큰에 키가 지정되고 새로 고침 회전 후에도 유지됩니다. 개발 모드에서는 단일 환경 자격 증명(SISENSE_DOMAIN/SISENSE_TOKEN)이 사용자 머신에 유지됩니다. 디스크에 아무것도 유지되지 않습니다: fes-auth를 다시 시작하면 저장소가 지워집니다(모든 사람이 다시 로그인) — 데이터베이스와 저장 시 암호화 표면이 없다는 의도적인 트레이드오프입니다.

호스팅된 표면의 강화: IP별 로그인 속도 제한, CSRF 보호 로그인 양식, 요청 ID가 있는 액세스 로그, 호출별 도구 로그(도구 / 사용자 도메인 / 결과 / 기간).

권한 부여

사용자 지정 없음: 권한 부여는 Sisense의 작업입니다. 모든 도구 호출은 호출 사용자 자신의 Sisense 토큰으로 실행되므로 Sisense는 모든 API 호출에서 실제 권한을 적용하고 권한 오류는 클라이언트에 그대로 표시됩니다. 이것이 서버가 관리자 전용이 아닌 이유이기도 합니다 — 모든 Sisense 사용자는 정확히 자신의 범위를 얻습니다.

두 서비스 간의 신뢰

fes-auth ↔ fes-mcp 신뢰는 네트워크 수준입니다: 공유 비밀번호 없음. RS의 포트는 내부 네트워크 외부에서 절대 도달할 수 없어야 합니다(compose는 fes-auth만 게시). 심층 방어: FES_MCP_ALLOWED_SISENSE_ORIGINS는 RS가 X-Sisense-Url에서 허용할 Sisense 원본을 고정합니다.

변경

변경 도구는 FES_MCP_ALLOW_MUTATIONS=true일 때만 노출되며, 항상 destructiveHint를 전달하고, 비활성화되면 서버 측에서 두 번째 레이어로 차단되며, 변경 감사 로그에 기록됩니다.

그 위에 변경 도구는 실행 전에 사람에게 승인을 요청합니다 — MCP 유도(elicitation)를 통해, 해당 기능을 선언하는 클라이언트(Claude Code, Cursor, VS Code)에서. 호출 중간에 정확한 인수를 공개하는 진행/중단 대화 상자가 열립니다. 중단하거나 거부하면 아무것도 변경되지 않습니다. 유도가 없는 클라이언트(Claude Desktop, claude.ai)에서는 호출이 정상적으로 진행되고 클라이언트 자체 도구 승인 흐름과 destructiveHint 주석이 다른 MCP 서버와 마찬가지로 안전 장치입니다.

대화 상자 없이 진행하는 것은 의도적인 결정(실패-개방)이지 실수가 아닙니다: 유도는 선택적 클라이언트 기능이며 잘못된 동작을 하는 클라이언트가 자동으로 응답할 수 있으므로 엄격히 UX로 취급됩니다 — 권한 부여 경계는 항상 사용자 자신의 Sisense 권한입니다.

LLM 공급자로의 데이터 흐름

이 서버에는 요약 또는 데이터 편집 레이어가 없습니다: 모든 도구 결과 — {ok, count} 메타데이터가 아닌 전체 행 — 가 MCP 클라이언트에 반환되고 모델의 컨텍스트에 들어갑니다. 이것은 의도된 설계이며 다단계 도구 체이닝이 작동하게 하는 것입니다: 모델은 실제 데이터를 볼 때만 한 도구의 출력을 추론, 필터링, 다음 호출에 공급할 수 있습니다.

결과: 이 서버를 MCP 클라이언트에 연결하는 사람은 Sisense 데이터(대시보드 내용, 쿼리 결과, 사용자 목록 등)가 해당 클라이언트의 LLM 공급자(예: Claude의 경우 Anthropic)로 자신의 해당 공급자와의 약관에 따라 흐르는 것을 수락하는 것입니다. 서버는 이를 강제하거나 범위를 지정할 수 없습니다. 배포별로 의식적으로 수락해야 하는 사항입니다.

권장 사용 지침

• 읽기 전용으로 시작: 비프로덕션 환경에서 확신이 생길 때까지 FES_MCP_ALLOW_MUTATIONS=false(기본값)를 유지하십시오.

• config/allowlist.txt를 배포에 실제로 필요한 도구로 줄이십시오 — 도구가 적을수록 데이터 노출이 줄어들고 승인 스토리가 명확해집니다.

• 탐색하는 동안 비프로덕션 Sisense 인스턴스를 선호하십시오. 도구는 로그인한 사용자의 권한만큼만 안전합니다.

• 유도(elicitation)를 지원하는 MCP 클라이언트(Claude Code, Cursor)로 파괴적 작업을 테스트하여 확인 대화 상자를 볼 수 있도록 하십시오.

구성

테스트

uv run python -m pytest

(python -m이 중요합니다: 저장소 루트를 sys.path에 넣어 테스트 모듈의 from tests.conftest import … 가져오기가 의존합니다.)

49개의 테스트, 네트워크와 자격 증명이 필요 없음(Sisense와 SDK는 모킹됨): 레지스트리 선택, 디스패처 검증/오류, MCP 왕복, 변경 확인(승인/중단/거부/기능 없음), 업스트림 자격 증명 검증(주입된 헤더, 401 계약, 출처 허용 목록, TTL 폐기), 그리고 완전한 AS+RS 분할 — ?target= 유무에 따른 OAuth 흐름, 검색 메타데이터, 프록시된 도구 호출, 갱신 로테이션, Sisense 측 폐기 시 자가 복구, 그리고 남용 경로(위조된 CSRF, 무차별 대입 속도 제한, 만료된 세션).

레지스트리 재생성

./refresh_registry.sh   # rebuild config/ from the installed PySisense SDK

새 SDK 메서드는 레지스트리에 추가되지만 config/allowlist.txt에 명시적으로 추가될 때까지 숨김 상태로 유지됩니다.

지원 및 기여

이 프로젝트는 Sisense Field Engineering이 유지 관리하는 실험적 커뮤니티 기여 프로젝트이며 "있는 그대로" 제공됩니다.

• GSS 티켓을 열지 마십시오 — 이는 GA Sisense 기능이 아닙니다.

• 사용 관련 질문이나 시작에 대한 도움이 필요하면 Customer Success Manager(CSM)에게 문의하십시오. CSM이 피드백을 Field Engineering 팀으로 전달합니다.

• 이슈와 기여는 저장소를 통해 환영합니다.

라이선스

MIT