Skip to main content
도구 연결은 AI가 외부 시스템의 기능을 호출(Function Calling)할 수 있게 해주는 기능입니다. OpenAPI 스펙 기반 REST API 또는 MCP(Model Context Protocol) 서버를 연결하면, AI가 대화 중 적절한 시점에 자동으로 도구를 호출합니다.

​
도구란?

도구는 AI의 능력을 외부 시스템으로 확장하는 인터페이스입니다. AI가 학습 데이터에 없는 실시간 정보를 조회하거나, 외부 시스템에 작업을 요청할 수 있습니다.

​
활용 예시

연결 대상할 수 있는 일
CRM 시스템고객 정보 조회, 영업 기회 등록
티켓 시스템이슈 생성, 상태 업데이트
HR 시스템휴가 신청, 직원 정보 조회
날씨/주가 API실시간 외부 데이터 제공
사내 데이터 API매출, 재고 등 비즈니스 데이터 조회

​
지원 프로토콜

OpenAPI

REST API 표준 스펙(구 Swagger). 대부분의 웹 서비스가 제공하는 범용 프로토콜입니다.

MCP

Model Context Protocol. AI 전용 도구 서버 프로토콜로, 더 안전하고 효율적인 통합을 지원합니다.

​
도구 목록

워크스페이스 > 도구에서 등록된 모든 도구 연결을 확인합니다. 목록에서 각 도구는 다음 정보를 표시합니다:
항목설명
이름도구 표시 이름
설명도구 용도 설명
작성자도구를 생성한 사용자
수정 시간마지막 수정 시점 (상대 시간)
목록 상단에는 검색창이 있어 이름이나 설명으로 도구를 검색할 수 있습니다. 각 도구 카드의 메뉴(...)에서는 삭제가 가능합니다.

​
도구 생성

도구 생성은 두 단계로 이루어집니다: 기본 정보 입력(CreateTool) 후 상세 페이지(ToolDetail)에서 연결을 구성합니다.
1

새 도구 만들기

워크스페이스 > 도구 목록 우측 상단의 + 버튼을 클릭합니다.생성 폼에 다음 정보를 입력합니다.
필드 라벨설명예시
이 도구는 무엇을 하나요? (이름)도구 표시 이름”고객 관리 API”
이 도구를 어떻게 사용할 수 있나요? (설명)도구 용도 설명”CRM 시스템 고객 정보 조회 및 관리”
접근 권한공개 또는 특정 그룹/사용자에게 제한공개, 또는 특정 그룹/사용자 지정
접근 권한은 공개(Public)와 비공개(특정 그룹/사용자 지정)로 나뉩니다. 비공개 시 읽기(Read)와 쓰기(Write) 권한을 그룹/사용자별로 세분화할 수 있습니다.
도구 만들기 버튼을 클릭하면 도구가 생성되고 상세 설정 페이지로 자동 이동합니다.
2

상세 페이지에서 연결 구성

생성 후 자동으로 이동한 상세 페이지(/workspace/tools/{id})에서 실제 연결을 설정합니다. 상세 페이지의 구성은 아래 OpenAPI 도구 연결 및 MCP 도구 연결 섹션을 참고하세요.

​
OpenAPI 도구 연결

OpenAPI(구 Swagger) 스펙을 제공하는 REST API를 연결하는 방법입니다. 도구 상세 페이지에서 아래 설정을 진행합니다.

​
연결 설정 필드

필드설명기본값
Connection TypeOpenAPI 또는 MCP 선택 드롭다운OpenAPI
API Base URLOpenAPI 서버의 기본 URL—
OpenAPI Spec PathOpenAPI 스펙 파일 경로openapi.json
Auth Type인증 방식 선택Bearer Token
API KeyBearer Token 방식일 때 토큰 값—
Enabled연결 활성화/비활성화 토글활성화
API Key 필드에 Bearer 토큰 값을 입력합니다. API 호출 시 Authorization: Bearer <token> 헤더로 전송됩니다.
API Base URL: https://api.example.com
OpenAPI Spec Path: openapi.json
Auth Type: Bearer Token
API Key: sk-xxxxxxxxxxxxxxxx

​
연결 테스트 및 기능 확인

설정 완료 후 연결 테스트(Test Connection) 버튼을 클릭합니다. 연결 성공 시 우측 사용 가능한 기능(Available Functions) 패널에 API 엔드포인트 목록이 자동으로 표시됩니다. 각 기능 항목에는 HTTP 메서드(GET, POST 등), 이름, 설명, 경로가 표시되며, 마우스를 올리면 파라미터 상세 정보를 확인할 수 있습니다.

​
MCP 도구 연결

MCP(Model Context Protocol)는 AI 모델과 외부 도구 간의 통신을 위한 전용 프로토콜입니다. 도구 상세 페이지에서 Connection Type을 MCP로 변경한 후 아래 설정을 진행합니다.

​
연결 설정 필드

필드설명기본값
Connection TypeMCP 선택—
MCP Server URLMCP 서버 주소 (SSE 엔드포인트)—
Auth Type인증 방식 (None / Bearer Token / API Key)None
Token / API Key인증 방식에 따른 인증 값—
Additional Headers추가 HTTP 헤더 (선택)—
Enabled연결 활성화/비활성화 토글활성화

​
MCP 인증 방식

인증 없이 MCP 서버에 연결합니다. 로컬 또는 내부 네트워크의 MCP 서버에 적합합니다.

​
추가 헤더 설정

MCP 서버가 커스텀 헤더를 요구하는 경우 Additional Headers 필드에 입력합니다. 키: 값 형태로 한 줄에 하나씩 작성합니다. 
X-Custom-Header: value
X-Another-Header: another-value

​
연결 테스트

연결 테스트(Test Connection) 버튼을 클릭하면 MCP 서버에 연결하여 제공하는 도구 목록을 조회합니다. 연결 성공 시 우측 사용 가능한 기능 패널에 MCP 도구 목록이 표시됩니다.

​
Tool Description (에이전트용 설명)

도구 상세 페이지 상단에는 Tool Description 필드가 있습니다. 이 필드는 에이전트가 어떤 상황에서 이 도구 서버를 사용해야 하는지 판단하는 데 사용됩니다.
  • 직접 설명을 작성하거나, AI 버튼을 클릭하여 연결된 기능 목록을 기반으로 자동 생성할 수 있습니다
  • AI 생성 시 사용할 모델을 드롭다운에서 선택할 수 있습니다 (기본: 시스템 기본 모델)
  • 연결 테스트 후 기능 목록이 로드된 상태에서만 AI 생성이 가능합니다
Tool Description을 잘 작성하면 에이전트가 적절한 시점에 도구를 선택하는 정확도가 높아집니다. 예: “프로젝트 이슈 관리, 메시지 전송, API 통합이 필요할 때 사용합니다.”

​
도구 활용

​
에이전트에 도구 연결

도구를 에이전트에 연결하면 AI가 대화 중 자동으로 적절한 시점에 도구를 호출합니다.
  1. 워크스페이스 > 에이전트에서 에이전트 편집 화면을 엽니다
  2. 도구 섹션에서 연결할 도구를 선택합니다
  3. 저장합니다

​
채팅에서 도구 호출 과정

AI가 사용자 질문을 분석하여 도구가 필요한지 판단하고, 필요한 경우 자동으로 호출합니다. 
사용자: 고객 ID 12345의 정보를 조회해줘

AI: [CRM API 호출 중...]

고객 정보를 조회했습니다:

| 항목 | 값 |
|------|-----|
| 이름 | 홍길동 |
| 이메일 | hong@example.com |
| 등급 | VIP |
| 최근 구매일 | 2024-01-15 |

​
도구 관리

​
편집

도구 목록에서 카드를 클릭하면 상세 페이지로 이동하여 연결 설정, 이름, 설명, Tool Description 등을 수정할 수 있습니다. 상세 페이지 우측 상단의 Save 버튼으로 변경 사항을 저장합니다.

​
삭제

도구 목록에서 카드 우측의 메뉴(...)를 클릭하고 삭제를 선택합니다. 삭제 확인 다이얼로그에서 확인하면 도구가 영구 삭제됩니다.

​
접근 권한 변경

상세 페이지 우측 상단의 Access 버튼을 클릭하여 접근 권한을 변경할 수 있습니다. 읽기(Read)와 쓰기(Write) 권한을 그룹/사용자별로 지정하거나, 공개(Public)로 설정할 수 있습니다.

​
보안 고려사항

보안 기능설명
암호화 통신모든 API 호출은 TLS로 암호화
자격 증명 저장API 키는 데이터베이스에 JSON 형태로 저장됩니다
접근 제어읽기/쓰기 권한별 도구 사용 제한
API 키는 평문으로 저장되므로 정기적으로 순환(rotate)하세요. 사설 네트워크 내 API만 연결하고, 필요시 IP 화이트리스트 또는 VPN/Private Endpoint를 활용하세요. 데이터베이스 접근 권한을 적절히 제한하여 자격 증명을 보호하세요.

​
트러블슈팅

원인해결 방법
URL 오류API Base URL 및 OpenAPI Spec Path를 재확인합니다
인증 실패API 키/토큰 유효성을 확인합니다
네트워크방화벽/프록시 설정을 확인합니다
CORS서버 측 CORS 설정을 확인합니다
원인해결 방법
권한 부족API 권한(scope)을 확인합니다
Rate Limit호출 빈도를 조절합니다
서버 오류외부 서비스 상태를 확인합니다
원인해결 방법
URL 형식SSE 엔드포인트 URL 형식을 확인합니다 (예: https://mcp.example.com/sse)
인증 방식 불일치서버가 요구하는 인증 방식(None/Bearer Token/API Key)과 설정이 일치하는지 확인합니다
연결 비활성화Enabled 토글이 활성화 상태인지 확인합니다

​
FAQ

OpenAPI(Swagger) 스펙을 제공하는 API는 모두 연결 가능합니다. 스펙이 없는 경우 MCP 서버를 직접 구축하거나, OpenAPI 스펙을 별도로 작성해야 합니다.
외부 API 사용 시 해당 서비스의 과금 정책이 적용됩니다. Cloosphere 자체에서는 도구 호출에 대한 추가 비용이 없습니다.
모든 통신은 TLS로 암호화되며, 접근 권한을 세밀하게 설정하여 사용을 제한할 수 있습니다. 가드레일을 함께 사용하면 민감 정보 유출을 추가로 방지할 수 있습니다.
기존에 OpenAPI 스펙을 제공하는 REST API가 있다면 OpenAPI를 선택하세요. AI 전용 도구 서버를 새로 구축하거나, MCP 호환 서버를 이미 보유하고 있다면 MCP를 선택하세요.

​
다음 단계

에이전트에 도구 연결

도구를 에이전트에 연결하여 AI 능력을 확장합니다

용어집 활용

도메인 용어를 관리하여 AI 답변 품질을 높입니다