연동 준비 가이드 (IT 담당자용)

모노클 AI에 사내 DB나 사내 시스템을 연결할 때 IT·보안 담당자가 준비할 내용입니다. 등록은 모노클 워크스페이스 관리자가 합니다. 전체 흐름은 앱(MCP) 연동을 참고하세요.

연결 방식	준비할 것
사내 DB 연결	모노클 전용 계정(조회만 필요하면 읽기 전용), 방화벽 허용 (개발 없음)
커스텀 앱	MCP 서버 개발·배포, 로그인 방식 결정

A. 사내 DB 연결

사내 DB 연결의 네트워크 구조 — 모노클 서버 IP만 허용하고, 읽기 전용 계정으로 조회합니다

1. 범위 정하기

지원 DB: PostgreSQL, MySQL, Oracle, Microsoft SQL Server
현업이 정한 질문 3~5개에 필요한 표와 컬럼만 엽니다.
급여 등 민감한 표는 제외하거나, 합계만 보여 주는 뷰(View)를 만들어 그 뷰만 엽니다.
운영 DB 부담이 걱정되면 읽기 전용 복제본(replica)을 연결합니다.

2. 전용 계정 만들기

아래는 조회만 허용하는 읽기 전용 계정 예시입니다. 조회 도구만 쓸 계획이라면 이 방식을 권장합니다. 등록·수정·삭제 도구를 쓸 계획이라면 해당 표에 필요한 권한만 추가로 주세요.

모노클 전용 계정을 만들고 필요한 표에만 조회 권한을 줍니다. 이름은 환경에 맞게 바꾸세요.

PostgreSQL

CREATE ROLE monocle_readonly WITH LOGIN PASSWORD '<강력한_비밀번호>';
GRANT CONNECT ON DATABASE hr TO monocle_readonly;
GRANT USAGE ON SCHEMA public TO monocle_readonly;
GRANT SELECT ON public.employees TO monocle_readonly;
-- (권장) 보조 안전장치: 기본 트랜잭션을 읽기 전용으로
ALTER ROLE monocle_readonly SET default_transaction_read_only = on;

MySQL

-- 접속 허용 호스트에 모노클 서버 IP를 적습니다 ('%'(모든 IP)는 쓰지 마세요)
CREATE USER 'monocle_readonly'@'모노클_서버_IP' IDENTIFIED BY '<강력한_비밀번호>';
GRANT SELECT ON hr.employees TO 'monocle_readonly'@'모노클_서버_IP';

Microsoft SQL Server

CREATE LOGIN monocle_readonly WITH PASSWORD = '<강력한_비밀번호>';
USE hr;
CREATE USER monocle_readonly FOR LOGIN monocle_readonly;
GRANT SELECT ON dbo.employees TO monocle_readonly;

SQL Server는 혼합 인증 모드여야 합니다. Azure SQL Database는 USE 대신 대상 DB에 직접 접속해 사용자를 만듭니다(CREATE USER ... WITH PASSWORD).

Oracle

CREATE USER monocle_ro IDENTIFIED BY "<강력한_비밀번호>";
GRANT CREATE SESSION TO monocle_ro;
GRANT READ ON hr.employees TO monocle_ro;  -- READ: 12.1.0.2 이상(이전 버전은 SELECT), 조회만 허용

Oracle은 도구 SQL에 hr.employees처럼 스키마 이름을 붙여야 합니다. 멀티테넌트(CDB) 환경이면 대상 PDB에 접속해 계정을 만듭니다.

공식 문서: PostgreSQL · MySQL · SQL Server · Oracle

3. 접속 허용

방화벽·보안 그룹에서 모노클 서버 IP → DB 포트를 허용합니다. 모노클 서버 IP는 고객센터(support@monocle-ai.com)로 요청하세요.

DB 위치	설정할 곳
AWS RDS	보안 그룹 인바운드 규칙, 퍼블릭 액세스 설정
네이버 클라우드	ACG 인바운드 규칙
Azure SQL	서버 방화벽 IP 규칙
Oracle Autonomous DB	접근 제어 목록(ACL)에 IP 추가
사내 서버(IDC)	회사 방화벽, 공인 IP·포트 연결

DB 설정도 확인하세요. PostgreSQL은 listen_addresses·pg_hba.conf, MySQL은 bind-address가 외부 접속을 막지 않아야 합니다. 설정 후 모노클 관리자 화면의 연결 테스트로 확인하세요.

보안 정책상 DB를 외부에 열 수 없다면, 연결 방식을 고객센터(support@monocle-ai.com)와 먼저 상의하세요.

4. 클라우드 DB · Oracle Autonomous DB

풀러(pooler) 주소와 직접 연결 주소가 따로 있다면 직접 연결 주소를 씁니다.
Oracle Autonomous DB는 포트가 보통 1522입니다(기본 입력값 1521을 바꾸세요). mTLS가 필요하면 콘솔에서 인스턴스 Wallet zip을 받아 ewallet.pem만 꺼내 둡니다. Wallet 파일과 비밀번호는 관리자 화면에서 직접 입력하는 것을 권장합니다.

① Oracle 선택 ② 서비스 이름 ③ Wallet 파일·비밀번호 (mTLS인 경우만)

5. 워크스페이스 관리자에게 전달

항목	예시
DB 종류 / 주소 / 포트	PostgreSQL / hr-db.example.co.kr / 5432
데이터베이스 이름 (Oracle은 서비스 이름)	hr
계정	monocle_readonly (비밀번호는 IT 담당자가 관리자 화면에 직접 입력 권장)
열어 둔 표·컬럼	employees (department, job_level, status, hired_at)

B. MCP 서버 (커스텀 앱)

모노클 AI ↔ MCP 서버 ↔ 사내 시스템의 연결 구조

1. 연결 요건

항목	요건
서버 형태	원격(Remote) MCP 서버. 로컬(stdio) 서버는 연결할 수 없습니다
주소	`https://` + 유효한 TLS 인증서, 인터넷에서 접속 가능
전송 방식	Streamable HTTP 권장
로그인	OAuth 또는 API 키 권장 (인증 없음은 공개 정보만). OAuth는 모노클이 자동 감지하며, 안 되면 Client ID·Secret 발급

OAuth 리디렉션 주소, API 키 전달 형식, 모노클 서버 IP는 고객센터(support@monocle-ai.com)에서 안내합니다.

2. 도구 설계

조회 도구부터 공개하고, 등록·실행 도구는 단계적으로 추가합니다.
도구 설명은 구체적으로. AI는 설명을 보고 도구를 고릅니다.
인자에 형식과 예시를 적습니다. 예: YYYY-MM-DD
결과는 필요한 필드만, 목록은 건수를 제한합니다.

3. 예제 (Python 공식 SDK 2.x)

그룹웨어의 기존 API를 도구로 감싸는 최소 예제입니다. 함수 설명(docstring)이 AI가 읽는 도구 설명이 됩니다.

# pip install "mcp[cli]>=2" httpx
import os
import httpx
from mcp.server import MCPServer
from mcp.server.transport_security import TransportSecuritySettings

mcp = MCPServer("groupware")

@mcp.tool()
def list_pending_approvals(limit: int = 10) -> list[dict]:
    """결재 대기 문서 목록(문서번호·제목·기안자·기안일)을 최신순으로 조회합니다.
    '결재 대기 문서 보여줘' 같은 질문에 사용합니다."""
    r = httpx.get(
        "https://groupware.internal.example.co.kr/api/approvals/pending",
        params={"limit": limit},
        headers={"Authorization": f"Bearer {os.environ['GROUPWARE_API_TOKEN']}"},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()["items"]

if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",  # 기본 주소: http://127.0.0.1:8000/mcp
        transport_security=TransportSecuritySettings(
            allowed_hosts=["mcp.example.co.kr", "mcp.example.co.kr:*"],
        ),
    )

HTTPS 리버스 프록시 뒤에 두고 https://mcp.example.co.kr/mcp로 공개합니다. allowed_hosts에 실제 도메인을 넣지 않으면 모든 요청이 421 Invalid Host header로 거부됩니다.

이 예제는 구조를 보여 주기 위해 인증을 뺐습니다. 그대로 공개하면 주소를 아는 누구나 호출할 수 있으니, 실제 배포 전에 OAuth 또는 API 키 검증을 꼭 추가하세요.

직원별 권한이 필요하면 OAuth로 로그인한 사용자 토큰을 서버에서 검증하고, 그 사용자 기준으로 그룹웨어 권한을 적용하세요. 모노클에서 받은 토큰을 그룹웨어에 그대로 넘기면 안 됩니다. (MCP 인증 사양)

4. 연결 전 테스트

MCP Inspector로 도구 목록과 호출 결과를 확인한 뒤 워크스페이스 관리자에게 주소와 로그인 방식을 전달합니다.

# Node.js 22.19 이상
npx @modelcontextprotocol/inspector --server-url https://mcp.example.co.kr/mcp --transport http

5. 보안 체크리스트

HTTPS로만 공개하고 유효한 인증서를 쓴다
사내 시스템 호출용 계정·토큰은 연동 전용, 최소 권한
처음엔 조회 도구만 공개
인자 값을 검증하고 SQL·명령어에 그대로 붙이지 않는다
응답에 비밀번호·토큰·주민등록번호 등을 넣지 않는다
도구 호출 기록(누가·언제·무엇을)을 남긴다

참고 자료

MCP for Beginners 한국어판 (Microsoft): MCP 서버 개발·보안·배포 무료 과정
MCP 보안 모범 사례 (영문)

보안 담당자 FAQ

Q. AI가 DB 데이터를 바꾸거나 지울 수 있나요?

워크스페이스 관리자가 등록한 도구에 따라 다릅니다. 도구에는 조회(SELECT)뿐 아니라 등록·수정·삭제(INSERT·UPDATE·DELETE) 문장도 넣을 수 있고, 그런 도구는 AI가 대화 중에 실행합니다. 표 구조를 바꾸는 문장과 여러 문장을 이어 붙인 SQL은 저장 단계에서 거부됩니다. 데이터가 바뀌지 않게 하려면 읽기 전용 계정을 연결하세요. DB 권한으로 수정이 막힙니다.

Q. AI가 임의의 SQL을 실행할 수 있나요?

아니요. 등록된 SQL의 값 자리(인자)만 채우므로 SQL 구조나 조회 대상을 바꿀 수 없습니다.

Q. DB 통신은 암호화되나요?

DB 연결 암호화(SSL/TLS) 설정은 고객센터(support@monocle-ai.com)로 문의하세요.

Q. DB 비밀번호는 어떻게 보관되나요?

암호화해 저장하며, 저장 후 화면에 다시 표시되지 않습니다.

Q. 누가 데이터를 볼 수 있나요?

사내 DB는 접근 정책에서 정한 그룹·역할만 사용할 수 있습니다. 커스텀 앱은 워크스페이스의 모든 사용자에게 보입니다. 사내 DB와 API 키 방식은 공용 계정 권한으로 동작하므로, 그 계정에 열어 둔 범위가 곧 직원이 쓸 수 있는 범위입니다. 직원별로 다르게 하려면 OAuth와 서버 쪽 권한 적용이 필요합니다.

Q. 조회 결과는 어디로 전달되나요?

답변을 만들기 위해 사용자가 고른 AI 모델에 전달되고, 해당 대화 기록에 남습니다. 대화 내용은 AI 모델 학습에 사용되지 않습니다.

Q. 즉시 차단하려면?

워크스페이스 관리자가 앱 메뉴에서 DB를 비활성화하거나 커스텀 앱을 삭제합니다. 고객사 쪽에서는 전용 계정·토큰을 잠그거나 방화벽 규칙을 지우면 바로 차단됩니다.

기능 소개