snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ko/user-guide/ai/capabilities/ai-agents.mdx

@@ -0,0 +1,30 @@
+---
+title: AI 에이전트
+description: 자동화 워크플로우에 AI 기능을 직접 통합합니다.
+---
+
+## 개요
+
+지능형 데이터 처리와 의사결정을 위해 자동화 워크플로우에 AI 기능을 직접 통합합니다.
+
+## 기능
+
+| 기능              | 설명                           |
+| --------------- | ---------------------------- |
+| **AI 작업**       | 모든 워크플로우에 AI 기반 단계를 추가합니다.   |
+| **데이터 강화**      | 외부 데이터를 사용해 레코드를 자동으로 강화합니다. |
+| **분류**          | 콘텐츠 분석을 기반으로 레코드를 분류합니다.     |
+| **요약**          | 텍스트 필드에서 요약을 생성합니다.          |
+| **사용자 지정 프롬프트** | AI가 데이터를 처리하는 방식을 정확히 정의합니다. |
+
+## 사용 사례
+
+* **리드 스코어링**: 유입 리드에 자동으로 점수를 매기고 우선순위를 지정합니다.
+* **데이터 정리**: 회사명과 연락처 정보를 표준화합니다.
+* **이메일 초안**: 회의 메모를 기반으로 후속 이메일을 생성합니다.
+* **레코드 라우팅**: 콘텐츠를 기반으로 적합한 팀 구성원에게 레코드를 할당합니다.
+
+## 관련 항목
+
+* [워크플로우 개요](/l/ko/user-guide/workflows/overview) — 자동화 기본 사항
+* [AI 권한](/l/ko/user-guide/ai/capabilities/permissions-access-control) — AI 에이전트에 대한 액세스 제어

packages/twenty-docs/l/ko/user-guide/ai/capabilities/ai-chatbot.mdx

@@ -0,0 +1,37 @@
+---
+title: AI 챗봇
+description: 자연어로 CRM 데이터와 상호작용할 수 있도록 도와주는 지능형 어시스턴트입니다.
+---
+
+## 개요
+
+자연어로 질문하면 어시스턴트가 CRM 데이터를 찾아 설명해 줍니다.
+
+## 기능
+
+| 기능            | 설명                                                            |
+| ------------- | ------------------------------------------------------------- |
+| **자연어 질의**    | 필터를 만들 필요 없이 쉬운 영어로 질문할 수 있습니다.                               |
+| **전체 데이터 접근** | 워크스페이스 전반의 레코드, 관계, 지표를 조회합니다.                                |
+| **페이지 컨텍스트**  | 현재 보고 있는 화면을 기준으로 "this company" 또는 "this opportunity"를 참조합니다 |
+| **대화형**       | 후속 질문도 이전 질의의 컨텍스트를 유지합니다.                                    |
+
+## 상호작용 예시
+
+### 레코드 찾기
+
+* "$50,000 이상인 모든 영업 기회를 보여줘"
+* "지난 2주 동안 내가 이메일을 보내지 않은 연락처를 찾아줘"
+* "헬스케어 산업의 회사를 목록으로 보여줘"
+
+### 인사이트 얻기
+
+* "내 전체 파이프라인 가치는 얼마야?"
+* "지난달에 성사된 거래는 몇 건이야?"
+* "어느 단계에서 정체된 영업 기회가 가장 많아?"
+
+### 페이지 컨텍스트 사용
+
+* "이 사람과의 상호작용을 요약해 줘" (연락처 페이지에서)
+* "이 회사와 연결된 영업 기회는 무엇이야?" (회사 페이지에서)
+* "이 거래는 마지막으로 언제 업데이트됐어?" (영업 기회 페이지에서)

packages/twenty-docs/l/ko/user-guide/ai/capabilities/mcp.mdx

@@ -0,0 +1,137 @@
+---
+title: MCP 서버
+description: Model Context Protocol을 사용하여 AI 어시스턴트를 Twenty 워크스페이스에 연결하세요.
+---
+
+Twenty는 Claude Desktop, Claude Code, Cursor, ChatGPT 등 AI 어시스턴트가 자연어로 CRM 데이터를 읽고 쓸 수 있도록 [MCP](https://modelcontextprotocol.io/) 서버를 제공합니다.
+
+MCP 엔드포인트로 **워크스페이스 URL**(Twenty에 접속할 때 사용하는 URL)을 사용하세요. Twenty Cloud에서는 워크스페이스 URL이 `https://{mycompany}.twenty.com` 또는 커스텀 도메인일 수 있습니다. 서버는 다음 위치에서 사용할 수 있습니다:
+
+| 환경         | MCP 엔드포인트                                                                  |
+| ---------- | -------------------------------------------------------------------------- |
+| **클라우드**   | `https://{your-workspace-url}/mcp` (예: `https://mycompany.twenty.com/mcp`) |
+| **셀프 호스팅** | `https://{your-domain}/mcp`                                                |
+
+## 인증 방법
+
+MCP 클라이언트를 인증하는 방법은 두 가지입니다: **OAuth**(권장) 또는 **API Key**.
+
+### 옵션 A — OAuth(권장)
+
+OAuth를 사용하면 MCP 클라이언트가 로그인할 수 있도록 브라우저 창을 엽니다. 비밀 값이 구성 파일에 저장되지 않으며, 토큰은 자동으로 갱신됩니다.
+
+<Note>
+OAuth를 사용하려면 [MCP Authorization 사양](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization)을 지원하는 MCP 클라이언트가 필요합니다. Claude Desktop, Claude Code, Cursor, ChatGPT가 이를 지원합니다.
+</Note>
+
+다음을 MCP 클라이언트 구성에 추가하고 `{your-workspace-url}`를 워크스페이스 호스트로 바꾸세요(예: `mycompany.twenty.com`):
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp"
+    }
+  }
+}
+```
+
+이것으로 완료입니다 — API 키는 필요하지 않습니다. 클라이언트가 처음 연결되면 다음을 수행합니다:
+
+1. `/.well-known/oauth-protected-resource` 및 `/.well-known/oauth-authorization-server`를 통해 Twenty의 OAuth 메타데이터를 발견합니다
+2. 동적 클라이언트 등록(RFC 7591)을 통해 OAuth 클라이언트로 등록합니다
+3. 액세스 권한 부여를 위해 브라우저를 엽니다
+4. 토큰을 수신하고 MCP 서버에 연결합니다
+
+이후 연결에서는 저장된 토큰을 재사용하고 자동으로 갱신합니다.
+
+### 옵션 B — API Key
+
+MCP 클라이언트가 OAuth를 지원하지 않거나 정적 자격 증명을 선호하는 경우, `Authorization` 헤더에 API 키를 전달하세요:
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+<Warning>
+API 키는 워크스페이스 데이터에 대한 액세스를 부여합니다. 버전 관리와 공유 도트파일에 포함하지 마세요.
+</Warning>
+
+API 키를 생성하려면 **Settings → MCP & APIs → API → + Create key**로 이동하세요. 자세한 내용은 [API](/l/ko/developers/extend/api#create-an-api-key)를 참조하세요.
+
+## 빠른 시작
+
+### 1. 구성 복사
+
+Twenty에서 **Settings → MCP & APIs → MCP**로 이동하세요. 인증 방법(OAuth 또는 API Key)을 선택하고, JSON 스니펫(이미 워크스페이스 URL이 포함되어 있습니다)을 복사하여 MCP 클라이언트의 구성 파일에 붙여넣으세요.
+
+| 클라이언트              | 구성 파일 위치                                                                                                                                     |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 또는 `%APPDATA%\Claude\claude_desktop_config.json` (Windows)         |
+| **Claude Code**    | `~/.claude.json` (사용자) 또는 `.mcp.json` (프로젝트)                                                                                                 |
+| **Cursor**         | 프로젝트의 `.cursor/mcp.json`, 또는 전역 `~/.cursor/mcp.json`                                                                                         |
+| **ChatGPT**        | **Settings → Apps & Connectors → Advanced settings**에서 Developer Mode를 켠 다음, **Settings → Apps & Connectors**의 **Create**를 사용해 MCP 서버를 추가하세요 |
+
+### 2. 연결
+
+MCP 클라이언트를 다시 시작하세요(또는 구성을 다시 로드하세요). OAuth를 사용 중이라면 액세스 권한 부여를 위해 Twenty로 리디렉션됩니다. API 키를 사용하는 경우 즉시 연결됩니다.
+
+### 3. 사용 시작하기
+
+AI 어시스턴트에게 CRM과 상호작용하도록 요청하세요:
+
+* *"가장 최근에 생성된 회사 5개를 보여줘"*
+* *"Acme Corp에 Jane Doe라는 새 사람을 생성해줘"*
+* *"1만 달러를 초과하는 열려 있는 모든 영업 기회를 찾아줘"*
+
+## 사용 가능한 도구
+
+연결되면 MCP 서버는 Twenty API를 미러링하는 도구들을 제공합니다. 권장 워크플로는 다음과 같습니다:
+
+1. **`learn_tools`** — 특정 도구의 입력 스키마를 가져오기
+2. **`execute_tool`** — 도구 실행
+
+도구 이름을 기억할 필요가 없습니다. AI 어시스턴트에게 무엇을 할 수 있는지 물어보면 `learn_tools`를 자동으로 호출합니다.
+
+## 권한
+
+MCP 연결은 인증된 사용자(OAuth)의 권한 또는 API 키에 할당된 역할을 상속합니다. MCP 서버가 수행할 수 있는 작업을 제한하려면:
+
+* **OAuth**: 사용자의 워크스페이스 역할이 적용됩니다.
+* **API Key**: **Settings → Members → Roles**에서 API 키에 역할을 할당하세요. 자세한 내용은 [권한](/l/ko/user-guide/permissions-access/capabilities/permissions)을 참조하세요.
+
+## 자가 호스팅 구성
+
+자가 호스팅 인스턴스의 경우 `{your-workspace-url}`을 서버 URL로 바꾸세요. 환경의 `SERVER_URL`이 Twenty 인스턴스의 공개 URL과 일치하는지 확인하세요 — 이는 OAuth 디스커버리 메타데이터를 생성하는 데 사용됩니다.
+
+```bash
+SERVER_URL=https://twenty.yourcompany.com
+```
+
+MCP 엔드포인트, OAuth 엔드포인트, 디스커버리 메타데이터는 모두 이 값을 기반으로 생성됩니다.
+
+## 문제 해결
+
+**"Unauthorized" 또는 401 오류**
+
+* OAuth: MCP 클라이언트에 저장된 토큰을 삭제하고 다시 연결하여 재승인하세요.
+* API Key: 키가 유효하며 만료되지 않았는지 확인하세요. 필요하다면 다시 생성하세요.
+
+**OAuth 플로우에서 브라우저가 열리지 않음**
+
+* MCP 클라이언트가 MCP Authorization을 지원하는지 확인하세요. 지원하지 않는 경우 API Key 방식으로 대체하세요.
+
+**연결 시간 초과**
+
+* 로컬 머신에서 MCP 엔드포인트 URL에 접근 가능한지 확인하세요. 자가 호스팅 인스턴스의 경우, 서버가 실행 중인지와 `SERVER_URL`이 올바르게 설정되어 있는지 확인하세요.

packages/twenty-docs/l/ko/user-guide/ai/capabilities/permissions-access-control.mdx

@@ -0,0 +1,35 @@
+---
+title: 권한 및 액세스 제어
+description: 워크스페이스에서 AI 에이전트가 액세스하고 수정할 수 있는 범위를 제어하세요.
+---
+
+## 개요
+
+AI 에이전트는 기존 권한 구조를 준수합니다. 이는 워크스페이스에서 자동화된 AI 프로세스가 액세스하거나 수정할 수 있는 대상을 정확히 통제하려는 팀에게 특히 중요합니다.
+
+## AI 에이전트에 역할 할당
+
+1. **설정 → 구성원 → 역할**로 이동하세요
+2. 할당할 역할 클릭
+3. **배정** 탭 열기
+4. **AI Agents**에서 **+ Assign to AI agent**를 클릭합니다
+5. 목록에서 AI 에이전트를 선택합니다
+6. 할당 확인
+
+## 왜 AI 에이전트에 역할을 할당하나요?
+
+| 이점         | 설명                                  |
+| ---------- | ----------------------------------- |
+| **보안**     | AI 에이전트가 액세스하거나 수정할 수 있는 데이터를 제한합니다 |
+| **규정 준수**  | AI가 필요한 데이터만 처리하도록 보장합니다            |
+| **제어**     | AI 자동화의 의도하지 않은 동작을 방지합니다           |
+| **감사 가능성** | 어떤 에이전트가 어떤 작업을 수행했는지 추적합니다         |
+
+<Note>
+워크플로 내에서 실행되는 AI 에이전트의 경우, 역할 할당은 워크플로에 더 광범위한 권한이 있더라도 해당 에이전트가 의도된 범위를 벗어난 데이터에 액세스하거나 수정하지 못하도록 보장합니다.
+</Note>
+
+## 관련
+
+* [권한](/l/ko/user-guide/permissions-access/capabilities/permissions) — 역할 생성 및 관리에 대한 자세한 정보
+* [AI 에이전트](/l/ko/user-guide/ai/capabilities/ai-agents) — 워크플로에서의 AI 기능