사용 가능 플랜: Entry, Professional, Enterprise, Enterprise Advanced

이 가이드는 Mattermost Agents 플러그인의 설치, 구성, 관리 방법을 다룹니다. Mattermost 인스턴스에 AI 기능을 설정하고 조직의 요구 사항에 맞게 구성하는 방법을 알아봅니다.

설치#

사전 요구 사항#

Agents 플러그인을 설치하기 전에 환경이 다음 요구 사항을 충족하는지 확인하세요.

• Mattermost Server v12.0.0 이상
• PostgreSQL 데이터베이스
• 시맨틱 검색을 사용하는 경우: pgvector 확장이 설치된 PostgreSQL
• 선택한 LLM 제공업체에 대한 네트워크 접근
• 외부로 나가는 LLM 트래픽이 HTTP 프록시를 거쳐야 하는 경우, Mattermost 서버 프로세스 또는 컨테이너 환경에 HTTP_PROXY와 HTTPS_PROXY를 설정하세요.
• 클라우드 LLM 서비스를 사용하는 경우 API 키

설치 단계#

사전 설치된 플러그인 사용#

Mattermost v10.3부터 Agents가 자동으로 설치되어 있어 대규모 언어 모델(LLM)을 바로 구성할 수 있습니다. 구성된 LLM이 없으면 Agents 패널에서 사용자에게 LLM을 구성하도록 안내합니다.

최신 버전 설치#

최신 기능과 개선 사항을 사용하려면 GitHub 릴리즈 페이지에서 최신 플러그인 버전을 다운로드하여 설치할 수 있습니다.

System Console > Plugin Management로 이동하여 플러그인 업로드를 클릭하고, 다운로드한 플러그인 파일(.tar.gz)을 선택한 다음 업로드를 클릭하여 System Console에서 플러그인을 설치합니다. 업로드가 완료되면 플러그인을 활성화한 다음, 아래 구성 섹션에 설명된 대로 플러그인 설정을 구성하세요.

구성#

플러그인 설정 접근#

System Console > Plugins > Agents로 이동하여 AI 서비스, 기본 봇, 웹 검색, 임베딩 검색, MCP 설정과 같은 플러그인 전체 설정을 구성합니다.

최상위 Agents 제품 페이지에서 에이전트를 생성하고 관리합니다. Agents 환경에 에이전트 선택 드롭다운이 있는 경우, 해당 드롭다운의 관리 링크를 사용하면 같은 페이지가 열립니다. System Console의 AI 봇 섹션은 전체 에이전트 편집기를 제공하지 않고 Agents 페이지로 연결됩니다.

플러그인 활성화#

사전 설치된 버전을 사용하는 경우 Agents가 자동으로 활성화됩니다. 더 최신 버전을 수동으로 설치한 경우에는 System Console > Plugins > Agents로 이동하여 플러그인 활성화를 True로 설정해 활성화해야 할 수 있으며, 그런 다음 System Console에서 구성을 완료하세요.

기본 구성#

Professional, Enterprise 또는 Enterprise Advanced 라이선스가 있는 경우 라이선스를 업로드하여 추가 기능을 사용할 수 있습니다(라이선스 요구 사항 참조). 라이선스가 없지만 Mattermost Enterprise Edition을 실행 중인 경우 Entry 라이선스가 자동으로 적용되며 Enterprise와 동일하게 동작합니다.

일반 설정에서는 플러그인 시스템을 전체적으로 활성화하거나 비활성화하고, 문제 해결을 위한 디버그 로깅(필요할 때만 사용)을 활성화하며, LLM 상호작용 추적을 위한 토큰 사용량 로깅을 활성화하고, API 호출용 호스트 이름 허용 목록을 구성할 수 있습니다. 외부로 나가는 LLM 제공업체 트래픽은 Mattermost 서버 프로세스에 HTTP_PROXY와 HTTPS_PROXY가 설정되어 있으면 이를 따릅니다.

AI 응답 링크 렌더링#

Mattermost Agents에는 AI가 생성한 Markdown 링크를 응답에서 클릭 가능한 링크로 렌더링할지 제어하는 설정이 있습니다.

• System Console 레이블: AI 생성 링크 렌더링
• 구성 키: allowUnsafeLinks
• 기본값: false

AI 생성 링크 렌더링이 False(기본값)로 설정되어 있으면 AI가 생성한 Markdown 링크는 일반 텍스트로 표시되며 클릭 가능한 링크로 렌더링되지 않습니다.

이 설정을 True로 설정하면 AI가 생성한 링크가 클릭 가능한 링크로 렌더링될 수 있습니다. 이는 보안과 맞바꾸는 선택입니다. AI 출력에 악성 목적지가 포함될 수 있으므로 피싱 및 데이터 유출 위험이 높아질 수 있습니다.

이 설정은 신뢰할 수 있는 환경이나, 사용자가 링크를 검증하도록 교육받았고 조직에 엔드포인트 보호 및 URL 통제가 마련되어 있는 등 위험이 완화된 환경에서만 활성화하세요.

서비스 구성#

Agents 연동에 사용할 LLM 제공업체(서비스)를 구성합니다. 서비스는 인증, 모델 기본값, 선택적 폴백 동작을 포함하여 LLM 제공업체와의 연결을 관리합니다. 서로 다른 제공업체나 구성에 맞춰 여러 서비스를 생성할 수 있으며, 여러 에이전트가 이를 공유할 수 있습니다.

System Console > Plugins > Agents로 이동하여 서비스 추가를 선택하세요.

폴백 서비스는 기본 서비스가 실패한 후 요청마다 시도되며, 다음 요청에서는 기본 서비스를 다시 시도합니다. 폴백 체인을 지원하며, 각 폴백은 자체 기본 모델, API 엔드포인트, 설정을 사용합니다. 순환이나 누락된 서비스처럼 유효하지 않은 폴백 체인은 설정 단계에서 눈에 띄게 실패합니다.

폴백은 구성된 서비스 중 어느 서비스가 LLM 요청을 처리할지 선택합니다. 사용자 권한, 채널 범위, 도구 실행은 변경하지 않습니다. 프롬프트 구성에 영향을 주는 예외가 하나 있습니다. 구조화된 출력을 요청하는 경우 전체 폴백 체인이 네이티브 스키마 지원을 사용할지 프롬프트 폴백을 사용할지를 사전에 결정합니다(구조화된 출력 참조). OpenAI 호환 서비스는 기본 서비스가 Responses API를 사용할 때의 채팅 전용 엔드포인트를 포함하여 로컬 또는 온프레미스 키 없는 폴백으로 사용할 수 있습니다.

입력 및 출력 토큰 제한은 각각 독립적으로 감지되므로, 한 필드는 자동 감지되고 다른 필드는 편집 가능한 상태로 남을 수 있습니다. 자동 감지된 모델에서 알 수 없는 모델이나 커스텀 모델로 다시 전환하면 Mattermost는 이전에 저장된 수동 값을 복원합니다.

구조화된 출력#

일부 요청은 스키마와 일치하는 JSON을 LLM에 요청합니다. 기계가 읽을 수 있는 출력이 필요한 에이전트 기능과, json_output_format 스키마를 제공하는 LLM Bridge 호출자가 여기에 해당합니다. 서비스의 구조화된 출력 설정은 해당 스키마가 제공업체에 전달되는 방식을 제어합니다.

저장되는 구성 키는 각 서비스 항목의 structuredOutputPolicy입니다. 빈 값은 auto를 의미하므로, 이 설정이 생기기 전에 구성된 서비스도 변경 없이 그대로 유효합니다.

이 설정은 서비스 하나의 기능을 설명하지만, 결정은 요청마다 한 번 이루어지며 해당 서비스의 전체 폴백 체인을 포괄합니다. 프롬프트 변환은 Mattermost가 실제로 요청을 처리할 서비스를 고르기 전에 이루어지기 때문입니다. 스키마는 가능한 모든 시도, 즉 기본 서비스와 그 폴백 체인의 모든 서비스가 자동(권장)에서 지원하는 것으로 알려져 있거나 네이티브 지원으로 표시된 경우에만 네이티브로 전송됩니다. 체인의 어느 한 곳이라도 프롬프트 폴백이 필요하면 요청 전체가 프롬프트 지침을 사용합니다. 따라서 서비스를 네이티브 지원으로 표시하더라도, 폴백이 필요한 서비스가 체인에 포함되어 있으면 네이티브 출력이 강제되지 않습니다.

구조화된 출력은 서비스에서만 구성합니다. 이전의 에이전트 수준 구조화된 출력 설정(에이전트 구성의 structuredOutputEnabled)은 더 이상 사용되지 않으며, 에이전트 편집기에 표시되지 않고 런타임에 무시됩니다. 서비스 정책은 에이전트 대화와 LLM Bridge를 통한 서비스 직접 호출 모두에 적용됩니다.

제공업체별 설정#

각 제공업체에는 고유한 구성 요구 사항이 있습니다.

AWS Bedrock의 경우 API 키/시크릿 필드에 AWS 자격 증명을 사용하여 인증을 구성하거나, AWS 인프라에서 Mattermost를 실행할 때 IAM 역할을 사용하여 인증을 구성할 수 있습니다.

Anthropic Claude 모델 관련 중요 사항: AWS Bedrock을 통해 Claude 모델을 사용하기 전에 AWS Bedrock Model Catalog에서 최초 사용(First Time Use, FTU) 양식을 한 번 제출해야 하며, Mattermost 서버의 IAM 역할에 Bedrock API 권한을 연결해야 합니다. 자세한 안내는 AWS Bedrock 설정 가이드를 참조하세요.

OpenAI 서비스는 항상 Responses API를 사용합니다. OpenAI 호환 서비스와 Azure 서비스는 Responses API 사용 설정을 유지하므로, 기존 Chat Completions 호환성이 여전히 필요한 엔드포인트에서는 이 설정을 비활성화할 수 있습니다.

제공업체별 구성에 대한 자세한 내용은 제공업체 가이드를 참조하세요.

에이전트 구성#

Agents 제품 페이지에서 에이전트를 생성하고 관리합니다. 최상위 Agents 제품 항목에서 열거나, 에이전트 선택 드롭다운의 관리 링크를 사용하여 해당 페이지로 이동합니다. 에이전트는 System Console > Plugins > Agents에 구성된 서비스 목록을 사용하며, 여러 에이전트가 같은 서비스 구성을 재사용할 수 있습니다. 라이선스가 필요한 기능에 대한 자세한 내용은 라이선스 요구 사항을 참조하세요.

에이전트를 관리할 수 있는 경우 에이전트 목록에서 해당 행을 선택하면 전체 페이지 구성 보기가 바로 열립니다. 더보기 메뉴에서는 계속 편집과 삭제를 사용할 수 있습니다. 에이전트로 돌아가기를 사용하면 목록으로 돌아갑니다.

에이전트를 생성하거나 편집할 때 전체 페이지 에이전트 구성 보기의 세 가지 탭을 사용합니다.

• 구성: 정체성, 모델 선택, 지침, 핵심 기능
• 액세스: 채널, 팀, 사용자 제한 및 위임된 에이전트 관리자
• MCP: 에이전트가 사용할 수 있는 MCP 도구

저장하지 않은 변경 사항이 있는 상태에서 에이전트로 돌아가기, 취소를 선택하거나 Escape 키를 눌러 에이전트 구성 보기를 벗어나려고 하면, Mattermost가 변경 사항을 취소하시겠습니까? 확인 창을 표시하며 취소와 계속 편집 버튼을 제공합니다.

구성 탭#

LLM별 에이전트 설정#

일부 기능은 선택한 서비스 유형에 따라 달라지며, OpenAI 호환과 Azure의 경우 해당 서비스에서 Responses API 사용이 활성화되어 있는지에 따라 달라집니다.

구조화된 출력은 에이전트 설정이 아닙니다. 서비스별로 구성하며(구조화된 출력 참조), 어떤 에이전트가 요청하든 스키마와 일치하는 JSON을 요청하는 모든 요청에 적용됩니다.

새 에이전트는 선택한 제공업체가 지원하는 경우 네이티브 웹 검색을 기본으로 활성화합니다. 네이티브 도구를 지원하지 않는 제공업체에서는 네이티브 도구 선택이 무시됩니다.

네이티브 도구 활동(수행한 검색, 가져온 페이지, 코드 실행)은 에이전트의 응답이 스트리밍되는 동안 응답에 표시되며 대화와 함께 보존됩니다. 네이티브 도구 통합의 알려진 제한 사항은 다음과 같습니다.

• Anthropic이 일시 중지하는(pause_turn) 매우 긴 제공업체 측 도구 루프는 재개되지 않으며, 응답은 그때까지 생성된 내용으로 끝납니다.
• 4.6보다 오래된 Claude 모델(동적 필터링이 없음)에서는 코드 실행과 함께 웹 검색 또는 웹 가져오기를 활성화하면 샌드박스를 사용할 수 없게 됩니다. 웹 도구가 있을 때마다 LLM 게이트웨이가 명시적 코드 실행 도구를 제외하여, 최신 모델이 수행하는 자동 주입과 충돌하는 것을 방지하기 때문입니다.
• Anthropic 코드 실행 샌드박스에서 생성된 파일은 에이전트가 공유할 수 있습니다. 에이전트는 공유할 만한 파일을 샌드박스의 출력 디렉터리에 복사하며, 해당 파일은 응답에 자동으로 첨부됩니다. 샌드박스의 다른 위치에 기록한 파일은 그대로 그곳에 남습니다. 서버의 파일 첨부 설정, 크기 제한, 게시물당 첨부 파일 수 상한, 요청한 사용자의 업로드 권한이 모두 적용됩니다. OpenAI 코드 인터프리터 파일은 아직 가져올 수 없으므로 이 기능은 Anthropic 에이전트에만 적용됩니다.
• 네이티브 도구 활동은 이후 요청에서 제공업체의 원래 결과 블록이 아니라 레이블이 붙은 요약(실행된 내용, 출력, 첨부를 위해 캡처된 파일 수)으로 모델에 다시 전달됩니다. 긴 명령과 출력은 잘리며 샌드박스 컨테이너는 재사용되지 않으므로, 모델은 재개 가능한 세션이 아니라 작업 기록을 보게 됩니다.

Anthropic 서비스의 경우 확장된 사고와 네이티브 구조화된 출력을 같은 요청에서 사용할 수 없습니다. JSON 스키마를 네이티브로 전송하는 요청은 해당 요청에서 확장된 사고를 건너뛰며, 그 외의 모든 요청은 계속 확장된 사고를 사용합니다. 프롬프트 폴백으로 처리되는 요청은 네이티브 스키마를 전송하지 않으므로 확장된 사고를 계속 사용합니다.

Responses API 경로가 없는 OpenAI 방식 엔드포인트가 필요하다면 OpenAI 서비스 유형을 사용하는 대신 OpenAI 호환 서비스를 사용하고 해당 서비스에서 Responses API 사용을 끄세요.

액세스 탭#

이 탭을 사용하여 에이전트와 상호작용하고 이를 관리할 수 있는 대상을 제어합니다.

• 채널 액세스는 에이전트를 멘션할 수 있는 채널을 제어합니다
• 사용자 액세스는 에이전트와 상호작용할 수 있는 사용자를 제어합니다
• 에이전트 관리자는 에이전트를 편집하고 삭제할 수 있습니다. 에이전트 생성자는 항상 관리자입니다

MCP 탭#

이 탭을 사용하여 에이전트가 MCP 도구를 사용하는 방식을 제어합니다. 이 탭은 도구 활성화가 켜져 있을 때만 사용할 수 있습니다.

• 동적 도구 로딩은 기본으로 켜져 있습니다. MCP 검색 및 로딩 도우미를 먼저 노출하고, 에이전트가 필요로 할 때만 전체 MCP 도구 스키마를 로드합니다. 이 에이전트에 전체 MCP 도구 목록을 처음부터 노출하려면 이 설정을 끄세요.
• 모든 MCP 도구 자동 활성화는 현재 사용 가능한 모든 MCP 도구와 나중에 추가되는 모든 MCP 도구에 대한 접근 권한을 에이전트에 부여합니다.
• 모든 MCP 도구 자동 활성화가 꺼져 있으면 에이전트가 사용할 수 있는 특정 MCP 도구를 선택합니다.
• 이전에 선택한 MCP 도구를 더 이상 사용할 수 없는 경우, 저장할 때 에이전트 구성에서 제거됩니다.

동적 도구 로딩과 자동 활성화되는 MCP 도구는 별개의 컨트롤입니다. 자동 활성화는 에이전트가 사용할 수 있는 도구를 제어하고, 동적 로딩은 도구 스키마가 모델에 노출되는 시점을 제어합니다.

에이전트의 표시 이름을 업데이트하면 연결된 Mattermost 봇의 표시 이름도 함께 업데이트됩니다. 에이전트를 삭제하면 연결된 Mattermost 봇 계정이 비활성화됩니다.

이전에 플러그인 구성에 저장되어 있던 레거시 봇은 시작할 때 데이터베이스 기반 에이전트로 마이그레이션된 다음 Agents 페이지에서 관리됩니다. 마이그레이션된 에이전트에는 생성자가 없으며 시스템 관리자가 관리할 수 있습니다.

커스텀 지침#

커스텀 지침 필드에 입력한 텍스트는 모든 요청의 프롬프트에 포함됩니다. 이를 사용하여 에이전트에 추가 컨텍스트나 지침을 제공하세요.

예를 들어 조직에서 사용하는 약어를 나열하면 에이전트가 조직의 용어를 이해하고 사용자가 정의를 물어볼 수 있습니다. 또는 특정 성격을 취하거나 특정 워크플로를 따르는 것과 같은 전문 지침을 줄 수도 있습니다. 각 에이전트의 지침을 개별적으로 맞춤 설정하면 특정 요구에 맞는 더욱 적합한 AI 환경을 만들 수 있습니다.

기본 제공 웹 검색 구성#

기본 제공 웹 검색 도구를 사용하면 모델이나 배포 환경이 제공업체 자체의 검색을 사용하지 않을 때 에이전트가 인터넷에서 최신 정보를 가져올 수 있습니다. 서비스가 지원하는 경우 제공업체의 네이티브 웹 검색을 우선 사용하세요.

기본 제공 웹 검색을 사용해야 하는 경우#

기본 제공 웹 검색은 네이티브 웹 검색 기능이 없는 LLM 모델을 위한 것입니다. 선택한 모델이 이미 네이티브 웹 검색을 제공하는 경우(OpenAI, Anthropic, Google Gemini, Google Vertex AI 또는 Responses API 사용이 활성화된 OpenAI 호환/Azure 서비스 등) 제공업체의 네이티브 구현을 대신 사용하기를 강력히 권장합니다. 네이티브 웹 검색 도구는 일반적으로 다음과 같은 이점을 제공합니다.

• 모델과의 더 나은 통합
• 더 신뢰할 수 있는 검색 결과
• 최적화된 성능

지원되는 제공업체의 네이티브 웹 검색 구성에 대한 자세한 내용은 위의 LLM별 에이전트 설정 섹션을 참조하세요.

제공업체 비교#

Mattermost는 기능이 서로 다른 두 가지 웹 검색 제공업체를 지원합니다.

Brave Search(권장)#

Brave Search는 AI 기반 검색에 더 우수한 환경을 제공합니다.

• AI를 위해 설계됨: Brave의 Search API는 LLM 연동을 위해 특별히 설계되고 최적화되었습니다
• 더 나은 콘텐츠 추출: 인용이 포함된, LLM에 바로 사용할 수 있도록 사전 처리된 요약을 반환합니다
• 더 적은 도구 호출: 후속 웹 페이지 가져오기나 스크레이핑 없이 완전한 답변을 제공하는 경우가 많습니다

중요: 관리자는 이 기능을 사용할 때 Brave의 Pro AI 플랜을 구독해야 합니다. Brave의 일반 Search API(비 AI 등급)를 사용하면 Brave의 서비스 약관을 위반하며 계정이 정지될 수 있습니다. Pro AI 플랜은 AI/LLM 사용 사례에 대해 라이선스가 부여된 플랜입니다.

Google Custom Search#

Google Custom Search는 Google의 검색 인덱스에 대한 접근을 제공하지만 몇 가지 중요한 제한 사항이 있습니다.

• 퍼스트파티 연동이 아님: Mattermost는 Google의 Custom Search API를 사용하며, 이 API는 google.com에서 직접 검색할 때와 같은 품질의 결과를 제공하지 않습니다
• 웹 스크레이핑에 의존: 검색 결과를 받은 후 Mattermost는 에이전트를 위한 콘텐츠를 추출하기 위해 웹 페이지를 스크레이핑해야 합니다. 많은 웹사이트가 자동화된 스크레이핑을 차단하거나 봇에게 제한된 콘텐츠만 반환합니다
• 속도 제한: Google Custom Search에는 엄격한 일일 할당량 제한이 있습니다

이러한 제한 사항 때문에 Google Custom Search는 에이전트 쿼리에 항상 최적의 결과를 제공하지 못할 수 있습니다.

구성#

기본 제공 웹 검색을 활성화하려면 다음을 수행하세요.

1. System Console > Plugins > Agents > Web Search로 이동합니다
2. 웹 검색 활성화를 True로 설정합니다
3. 제공업체 드롭다운에서 원하는 제공업체를 선택합니다
4. 제공업체별 설정을 구성합니다

Brave Search 구성#

Brave Search API 키를 얻으려면 다음을 수행하세요.

1. Brave Search API를 방문합니다
2. 계정에 가입합니다
3. Pro AI 플랜을 구독합니다(LLM 사용에 필수)
4. 대시보드에서 API 키를 생성합니다

경고: 반드시 Pro AI 플랜을 구독하세요. AI/LLM 연동에 다른 Brave Search 플랜을 사용하면 서비스 약관을 위반합니다.

Google Custom Search 구성#

Google Custom Search 자격 증명을 얻으려면 다음을 수행하세요.

1. Google Cloud Console에서 프로젝트를 생성합니다
2. Custom Search API를 활성화합니다
3. API 자격 증명(API 키)을 생성합니다
4. Google Programmable Search Engine에서 커스텀 검색 엔진을 설정합니다
5. 검색 엔진 ID(cx 매개변수)를 기록해 둡니다

공통 구성#

사용 및 제한 사항#

• API 비용을 관리하고 LLM이 무한 반복하는 것을 방지하기 위해 에이전트는 대화당 웹 검색 3회로 제한됩니다
• 에이전트는 한 대화 내에서 같은 검색 쿼리를 반복할 수 없습니다
• 검색 결과에는 출처 웹사이트로 연결되는 클릭 가능한 인용이 포함됩니다
• 도메인 거부 목록은 모든 제공업체에 적용되며 웹 페이지 가져오기에만 적용됩니다.

임베딩 검색 구성#

시맨틱 검색 기능을 활성화하려면 PostgreSQL 데이터베이스에서 pgvector 확장을 활성화한 다음, 제공업체(OpenAI 등), 임베딩용 모델, 선택한 임베딩 모델과 일치하는 차원을 포함한 임베딩 제공업체 설정을 구성해야 합니다. 임베딩 검색은 Enterprise 이상에서 사용할 수 있으며(라이선스 요구 사항 참조) 실험적 기능으로 제공됩니다. 대규모 데이터 세트에서는 성능이 달라질 수 있습니다.

필요에 따라 청킹 옵션을 구성하세요.

대규모 데이터 세트의 경우 대량 재인덱싱 처리량을 조정할 수 있습니다.

기본값은 OpenAI Tier 1 속도 제한 범위 내에서 여유 있게 유지됩니다. Azure OpenAI에서는 처리량이 배포의 분당 토큰 할당량으로 제한되므로, 워커 수를 늘려 이점을 얻으려면 할당량을 높이세요.

구성 후 초기 인덱싱 프로세스를 실행하세요. 과거 데이터가 방대한 경우 먼저 최근 N일간의 게시물 인덱싱을 설정한 다음 전체 재인덱싱을 실행하세요. 이 전체 재인덱싱이 과거 데이터의 기준선이 됩니다. 예를 들어 N=365는 수억 건의 오래된 게시물 대신 최근 1년 치만 인덱싱합니다.

대규모 데이터베이스 재인덱싱#

대규모 설치(게시물 수천만 건)에서는 전체 재인덱싱 전에 재인덱싱 인덱스 전략을 defer로 설정하세요. 삽입할 때마다 HNSW 인덱스를 유지하는 작업은 규모가 커질수록(특히 인덱스가 더 이상 메모리에 들어가지 않게 되면) 비용의 대부분을 차지합니다. 대량 로드 동안 인덱스를 삭제하고 이후 한 번만 다시 빌드하면 일반적으로 자릿수 하나만큼 빨라집니다.

지연된 재인덱싱에 대한 참고 사항은 다음과 같습니다.

• 재인덱싱이 시작된 시점부터 최종 인덱스 빌드가 끝날 때까지 시맨틱 검색을 사용할 수 없습니다(API가 HTTP 503을 반환). 라이브 게시물은 대량 로드 중에도 계속 인덱싱됩니다. 최종 빌드 중(대규모 DB에서는 수 시간)에는 라이브 인덱싱, 삭제, 보존 작업이 CREATE INDEX에서 막히지 않고 일시 중지됩니다. 따라잡기가 새 게시물을 복구하고, 복구 단계가 편집과 삭제를 처리하며, 보존 작업은 다음 예약 시점에 실행됩니다.
• 빌드 후 복구 단계. 인덱스가 생성되면 검색이 다시 반환되며, 그 후 작업은 라이브 인덱싱이 일시 중지된 동안 편집된 게시물을 다시 임베딩하기 위해 짧은 repairing 단계로 들어갑니다(따라잡기는 새 게시물을 처리). 빌드 후 복구가 끝나기 전에 작업이 중단되면 repairing 표식이 지속적으로 남으므로, 재개하거나 재인덱싱하여 마무리하세요. 이 단계에서도 검색은 작동하며, 복구가 완료될 때까지 최근 편집 일부가 약간 오래된 상태일 수 있습니다.
• 데이터베이스에서 빌드를 조정하세요. 플러그인은 서버 설정을 재정의하지 않습니다. HNSW 그래프를 maintenance_work_mem에 유지하세요. 표준 vector의 경우 대략 rows × (4 × dimensions + graph) 바이트이고, halfvec의 경우 rows × (2 × dimensions + graph) 바이트입니다. 그래프 오버헤드는 HNSW M에 따라 줄어듭니다(레이어당 약 2 × m개의 정수 링크이며, 기본값 m=8에서는 m=16에서 사용하던 기존 행당 약 300바이트라는 경험칙보다 훨씬 작습니다). 예: 256차원, m=8에서 요소당 약 1.4KB, 또는 게시물 2천만 건에 약 28GB. 256차원에서 반정밀도는 RAM을 절반으로 줄이지 않습니다. 그래프 간선은 여전히 정수 링크를 사용하므로 벡터 페이로드만 줄어듭니다. 이 예산을 초과하면 PostgreSQL이 디스크로 스필하며 빌드 속도가 약 40배까지 떨어질 수 있습니다. pgvector 0.6 이상은 max_parallel_maintenance_workers로 병렬화할 수 있습니다. halfvec에는 pgvector 0.7 이상이 필요합니다(Amazon RDS는 지원되는 엔진 버전에 포함).
• 장애 복구. 라이프사이클 상태는 지속적으로 유지됩니다. 재시작 후 인덱스 상태 확인에는 벡터 인덱스 상태가 표시되며, 재개하거나 전체 재인덱싱을 시작할 때까지 검색은 차단된 상태로 유지됩니다(플러그인은 활성화 중에는 인덱스를 다시 빌드하지 않습니다). 대량 로드 도중 취소하거나 실패한 경우에도 부분적인 코퍼스 위에서 인덱스를 다시 빌드하지 않고 인덱스를 삭제된 상태로 두므로, 재개하면 defer 방식으로 계속 진행됩니다. 전략이 다시 maintain으로 변경되었더라도 전체 재인덱싱이나 재개된 재인덱싱은 삭제된 인덱스를 다시 빌드하고 대기 중인 복구를 마무리합니다.
• 전략은 전체 재인덱싱에만 적용됩니다. 따라잡기는 인덱스를 삭제하지 않습니다. 라이브 인덱싱은 최종 빌드 중을 제외하고 인덱스를 유지합니다.
• 인덱스 보존 기간. N을 늘린 후의 따라잡기(예: 365 → 730, 또는 365 → 모든 게시물)는 삽입하는 동안 HNSW 인덱스를 유지하므로 오래 걸릴 수 있습니다. 매우 큰 코퍼스에서 1년 기간을 모든 게시물로 넓히는 경우에는 지연된 전체 재인덱싱이 여전히 더 나을 수 있습니다(모든 항목을 다시 임베딩하며, 빌드가 끝날 때까지 검색을 사용할 수 없음). 작업이 실행되는 중에 N을 변경해도 해당 작업의 기간은 바뀌지 않습니다. 새 범위를 적용하려면 작업을 중단하고 새 작업을 시작하세요.

권한 구성#

각 에이전트에 대해 팀 수준, 채널 수준, 사용자 수준 권한을 설정하여 AI 기능에 접근할 수 있는 대상을 구성합니다.

채널별 에이전트 자동 응답은 채널 관리 권한(채널 유형에 따라 manage_public_channel_properties 또는 manage_private_channel_properties)으로 제어되며, 쓰기 시 서버 측에서 확인됩니다. 채널 구성원은 현재 설정을 읽을 수 있습니다. 자동 응답 엔드포인트는 워크스페이스 기본 에이전트에 의존하지 않습니다. 기본 에이전트가 채널이나 사용자에 대해 제한된 경우(또는 구성된 에이전트가 전혀 없는 경우)에도 읽기와 쓰기가 작동하며, 쓰기는 선택한 에이전트의 채널 접근을 대신 검증합니다. 채널 에이전트 자동 응답은 Enterprise Advanced에서 사용할 수 있으며, 그보다 낮은 수준에서는 채널 설정 탭이 숨겨지고 저장된 설정은 비활성 상태가 됩니다. REST 엔드포인트를 통해 자동 응답을 끄는 데에는 라이선스가 필요하지 않으므로 기존 설정은 항상 해제할 수 있습니다. 채널 설정 탭 UI에는 Mattermost v11.10 이상이 필요합니다. 이전 서버에서는 탭이 숨겨지지만 REST 엔드포인트(GET/PUT /plugins/mattermost-ai/channel/{channelid}/autoreply)는 계속 사용할 수 있습니다.

속성 기반 접근 제어(ABAC)#

속성 기반 접근 제어를 사용하면 명시적인 사용자 또는 팀 목록을 유지하는 대신, 사용자 속성(예: user.attributes.department == "engineering")을 기준으로 작성한 정책으로 에이전트, LLM 서비스, MCP 서버를 사용할 수 있는 대상을 제한할 수 있습니다.

사전 요구 사항:

• 속성 기반 접근 제어가 활성화되고 라이선스가 적용된(Enterprise Advanced) Mattermost 서버(v12.0.0 이상). 플러그인은 서버를 확인하여 이 기능을 사용할 수 없으면 모든 ABAC UI를 숨깁니다. ABAC가 없는 서버에서는 레거시 액세스 모드가 사용자/팀 목록 확인을 유지하고 서비스와 MCP 서버에는 제한이 없지만, 속성 기반 모드의 에이전트는 사용할 수 없게 됩니다(정책이 사용자를 제한하는지 플러그인이 확인할 수 없으므로 모든 사용자가 거부됨). 서버를 업그레이드하거나 에이전트를 레거시 액세스 모드로 전환할 때까지 이 상태가 유지됩니다.
• 정책이 사용자 속성을 기준으로 작성되므로, 서버에 구성된 사용자 속성(커스텀 프로필 속성)

정책을 적용할 수 있는 리소스. 정책은 항상 하나의 리소스에 대한 use 작업을 허용하거나 거부합니다.

• 에이전트 — 에이전트의 액세스 탭에서 에이전트의 사용자 액세스를 속성 기반(액세스 정책)으로 설정한 다음 해당 위치에서 정책을 작성합니다. 이 모드에서는 에이전트의 허용/차단 사용자 및 팀 목록이 무시되며, 정책이 유일한 사용자 접근 관문입니다. 에이전트를 관리할 수 있는 모든 사용자, 즉 생성자, 에이전트 관리자, 다른 사용자의 에이전트 관리 권한을 가진 사용자는 간소화된(표) 편집기로 정책을 작성할 수 있으며, 시스템 관리자는 추가로 고급(CEL) 편집기를 사용할 수 있습니다.
• LLM 서비스 — 시스템 관리자가 System Console > Plugins > Agents의 서비스 패널에서 작성합니다. 시스템 관리자는 에이전트 액세스 탭과 마찬가지로 간소화된(표) 편집기와 고급(CEL) 편집기를 사용할 수 있으며, 고급 편집기는 표로 표시할 수 없는 표현식에 사용합니다. 서비스 정책은 에이전트별 제한에 더하여 해당 서비스를 기반으로 하는 모든 에이전트를 제한합니다. 또한 시스템 관리자가 아닌 사용자의 목록/선택기 표시 여부도 좌우합니다(표시 여부(서비스 및 에이전트) 참조).
• MCP 서버 — 시스템 관리자가 MCP 구성 탭에서 작성합니다(에이전트와 같은 간단 및 고급 편집기이며, 고급 편집기는 표로 표시할 수 없는 표현식에 사용). 정책은 원격 서버, 기본 제공(내장) Mattermost MCP 서버, 플러그인이 등록한 MCP 서버에 적용됩니다. MCP 서버 정책에 의해 거부된 사용자는 해당 서버의 도구를 조용히 잃게 되며, 채팅에 알림이 없고 도구가 그냥 표시되지 않습니다. 기본 제공 Mattermost 서버를 거부하면 해당 사용자에게서 제품 내 Mattermost 도구 대부분이 제거됩니다.

허용 및 거부 의미 체계. 플러그인은 각 요청에 대해 적용 가능한 정책을 평가하고 다음 규칙을 적용합니다.

• ABAC를 사용할 수 있고 리소스에 정책이 없는 경우 → 레거시 확인이 그대로 적용됩니다(레거시 액세스 모드의 에이전트는 사용자/팀 목록, 서비스/MCP 서버는 해당 없음). 속성 기반 모드의 에이전트는 모든 사용자를 허용합니다. 정책을 작성하기 전에는 플러그인을 설치하거나 업그레이드해도 아무것도 바뀌지 않습니다.
• 정책이 있는 경우 → 정책이 결정합니다. 일치하는 사용자는 허용되고 일치하지 않는 사용자는 거부됩니다.
• ABAC 엔진을 사용할 수 없는 경우(예: 라이선스가 만료되었거나 PDP 평가가 실패한 경우) → 평가는 안전 실패(fail closed) 방식으로 동작합니다. 제한 없는 접근으로 되돌아가지 않고, 속성 기반 에이전트와 정책이 있는 리소스에 대한 접근이 사용자에게 거부됩니다. 활성 정책이 없는 레거시 액세스 모드에서는 레거시 사용자/팀 목록이 계속 적용됩니다.

표시 여부(서비스 및 에이전트)#

목록과 선택기의 표시 여부는 리소스를 사용할 수 있는 대상을 따르며, 시스템 관리자에게는 한 가지 예외가 있습니다.

• 시스템 관리자는 서비스 ABAC 정책이 본인을 거부하더라도 AI 서비스와 해당 서비스를 기반으로 하는 에이전트를 볼 수 있습니다. 이를 통해 바인딩을 감사하고 접근 권한을 복구할 수 있습니다.
• 그 외 모든 사용자(에이전트 생성자와 위임된 에이전트 관리자 포함)는 실제로 사용할 수 있는 서비스와 에이전트만 봅니다. 에이전트의 경우 에이전트 액세스와 에이전트의 AI 서비스 액세스가 모두 필요합니다. 거부된 서비스와 에이전트는 목록과 선택기에서 생략되며, 유령 에이전트는 없고 ABAC 거부가 시스템 관리자가 아닌 사용자에게 "비활성" 에이전트로 표시되지도 않습니다.

절충점: 시스템 관리자가 아닌 에이전트 관리자가 ABAC 때문에 에이전트의 서비스에 대한 접근 권한을 잃으면 해당 에이전트가 보이지 않게 되며 직접 다시 바인딩하거나 수정할 수 없습니다. 시스템 관리자가 해당 사용자의 서비스 접근 권한을 복원하거나 에이전트의 서비스 바인딩을 변경해야 합니다.

리소스 라이프사이클 참고. 에이전트를 삭제하면 해당 정책이 최선의 노력으로 제거되지만, 구성에서 서비스나 MCP 서버를 삭제해도 해당 정책은 삭제되지 않습니다. 플러그인이 MCP 서버의 등록을 해제하는 경우에도 마찬가지로 정책은 그대로 남으며, 같은 플러그인이 같은 ID로 다시 등록하면 다시 연결됩니다. 같은 ID로 리소스를 다시 생성하면 이전 정책이 다시 적용됩니다. 그것이 원하는 결과가 아니라면 먼저 리소스의 정책 편집기에서 정책을 제거하세요.

작성 권한:

관리 작업#

플러그인 메트릭#

Agents의 메트릭은 기존 Mattermost 서버 메트릭 엔드포인트 아래의 /plugins/mattermost-ai/metrics 하위 경로를 통해 노출됩니다. 이는 성능용 수신 주소 구성 설정으로 제어됩니다. 기본 포트는 8067이며, 다음 메트릭을 사용할 수 있습니다.

• agents_system_plugin_start_timestamp_seconds: 플러그인이 시작된 시각입니다.
• agents_system_plugin_info: 플러그인 버전과 설치 ID입니다.
• agents_api_time_seconds: API 실행에 걸린 시간입니다.
• agents_http_requests_total: API 요청의 총 수입니다.
• agents_http_errors_total: HTTP API 오류의 총 수입니다.
• agents_llm_requests_total: 업스트림 LLM에 대한 요청의 총 수입니다.

토큰 사용량 추적#

Agents 플러그인은 청구와 사용량 분석을 지원하기 위해 모든 LLM 상호작용의 토큰 사용량을 추적할 수 있습니다. 활성화하면 토큰 사용량 데이터가 logs/agents/token_usage.log의 전용 파일에 JSON 형식으로 기록되며, 각 요청에 대한 상세 정보를 캡처합니다.

• 사용자 ID: 요청을 시작한 Mattermost 사용자
• 팀 ID: 요청의 팀 컨텍스트
• 봇 사용자 이름: 상호작용에 사용된 에이전트
• 서비스 ID 및 서비스 이름: 요청을 처리한 구성된 LLM 서비스이며, 기존 service_type 필드 바로 뒤에 service_id와 service_name으로 기록됩니다
• 수행 사용자 ID: 카탈로그 귀속에 사용되는 신원입니다. 요청한 사용자이거나, 에이전트가 서비스 계정 인증을 사용하는 경우 에이전트의 봇 사용자 ID입니다(이 경우 외부 MCP 서버는 공유 자격 증명을 사용하며, Mattermost 및 플러그인 도구는 계속 요청한 사용자로 실행됩니다)
• 도구 인증 모드: user 또는 service_account이며, 요청의 도구 카탈로그를 구성한 자격 증명 모드를 기록합니다
• 입력 토큰: LLM에 대한 요청의 토큰 수
• 출력 토큰: LLM 응답의 토큰 수
• 총 토큰: 입력과 출력을 합친 토큰 수
• 캐시 읽기 토큰: 보고된 경우, 제공업체 캐시에서 제공된 프롬프트 토큰 수
• 캐시 쓰기 토큰: 보고된 경우, 제공업체 캐시에 기록된 프롬프트 토큰 수
• 추론 토큰: 보고된 경우, 제공업체의 추론 또는 사고에 사용된 토큰 수
• 비용: 보고된 경우, 제공업체가 보고한 요청 비용

토큰 사용량 추적을 활성화하려면 System Console > Plugins > Agents로 이동하여 토큰 사용량 로깅 활성화를 True로 설정하세요. 활성화하면 로그 파일이 크기 100MB에 도달할 때 자동으로 순환되며, 순환된 로그 파일은 디스크 공간을 절약하기 위해 압축됩니다. 토큰 사용량 로그는 관리자에게 LLM 사용 패턴에 대한 가시성을 제공하며 비용 추적, 비용 분담, 리소스 계획, 디버깅에 사용할 수 있습니다. 사용량 데이터를 보고하는 제공업체는 이러한 필드를 채웁니다. 제공업체가 캐시된 토큰, 추론 토큰, 비용 세부 정보를 제공하지 않으면 해당 값은 0으로 유지됩니다.

service_id와 service_name은 추가된 필드이므로 로그 스키마 버전은 1로 유지되며 기존 쿼리와 대시보드는 계속 작동합니다.

LLM Bridge를 통해 서비스로 직접 전달되는 요청에는 뒤에 에이전트가 없습니다. 이러한 레코드에는 서비스 필드가 포함되며, 에이전트 차원인 agent_name, agent_username, bot_username, agent_user_id는 빈 문자열로 기록됩니다. 반면 Prometheus 토큰 사용량 메트릭은 이를 계속 bot_name="unknown"으로 집계합니다. 서비스 필드에서 service_name이 비어 있으면 구성된 서비스 자체의 이름이 비어 있다는 뜻이고(호출자가 서비스 ID로 접근하는, 비어 있음이 확인된 신원), 값이 unknown이면 신원이 누락되었다는 뜻입니다.

분석을 위한 토큰 사용량 로그 변환#

토큰 사용량 로그 파일에는 한 줄에 JSON 객체 하나가 들어 있어 Microsoft Excel 같은 도구와 직접 호환되지 않습니다. 다음 명령을 사용하여 로그를 다른 형식으로 변환하세요. 쉬운 JSON 파싱을 위해 각 명령에는 jq가 설치되어 있어야 합니다.

Excel 호환 JSON으로 변환:

jq -s '.' logs/agents/token_usage.log > token_usage.json

CSV 형식으로 변환:

echo "timestamp,user_id,acting_user_id,tool_auth_mode,team_id,bot_username,input_tokens,output_tokens,total_tokens,cached_read_tokens,cached_write_tokens,reasoning_tokens,cost" > token_usage.csv
jq -r '[.timestamp, .user_id, .acting_user_id, .tool_auth_mode, .team_id, .bot_username, .input_tokens, .output_tokens, .total_tokens, (.cached_read_tokens // 0), (.cached_write_tokens // 0), (.reasoning_tokens // 0), (.cost // 0)] | @csv' logs/agents/token_usage.log >> token_usage.csv

게시물 인덱싱#

게시물 인덱싱은 초기 설정 중에 자동으로 수행됩니다. 임베딩 제공업체, 모델, 차원 또는 벡터 정밀도(vector 대 halfvec)를 변경하려면 전체 재인덱싱이 필요합니다(차원이나 유형을 변경할 때는 재개를 사용하지 마세요. 재개는 기존 테이블 스키마를 유지합니다). 전체 재인덱싱은 차원이나 벡터 정밀도가 변경되면 새 벡터가 구성된 칼럼과 일치하도록 임베딩 테이블을 다시 생성합니다. HNSW M을 변경하려면 전체 재인덱싱이 아니라 벡터 인덱스 재빌드가 필요하며, 기존 임베딩은 재사용되고 HNSW 그래프만 다시 빌드됩니다. 업그레이드 후 기존 인덱스는 재빌드할 때까지 m=16으로 유지됩니다. 벡터 인덱스 재빌드로는 칼럼 유형을 변경할 수 없습니다.

최근 N일간의 게시물 인덱싱은 인덱싱이 거슬러 올라가는 기간을 제어합니다. 0(기본값)은 모든 게시물을 인덱싱합니다. 양수 N은 대규모 코퍼스에서 처음 실행하는 전체 재인덱싱의 과거 데이터 기준선입니다.

• N 증가(365 → 730, 또는 365 → 0/모든 게시물): 검색을 계속 사용할 수 있습니다. 따라잡기를 실행하여 이제 기간에 포함되었지만 아직 인덱스에 없는 게시물을 임베딩하세요. 따라잡기는 이미 존재하는 행을 다시 임베딩하지 않습니다. 기간을 넓히기 위해서만 전체 재인덱싱을 실행하지 마세요. 큰 폭으로 증가시킨 후의 따라잡기는 오래 걸릴 수 있으며 삽입하는 동안 HNSW를 유지합니다. 매우 큰 코퍼스에서 1년 기간을 모든 게시물로 넓히는 경우에는 지연된 전체 재인덱싱이 여전히 더 나을 수 있습니다(모든 항목을 다시 임베딩하며 검색을 사용할 수 없음).
• N 감소: 라이브 인덱싱과 이후의 재인덱싱은 더 좁아진 하한을 사용합니다. 이미 인덱스에 있는 행은 삭제되지 않으며 검색은 계속 해당 행을 반환합니다. RAM과 테이블 크기는 이후 전체 재인덱싱을 실행할 때까지 줄어들지 않습니다. 따라잡기는 여전히 임베딩 행이 없는 기간 내 게시물을 인덱싱합니다(NOT EXISTS). 인덱싱이 완료된 후에는 보통 추가 작업이 없습니다.
• N을 저장해도 따라잡기나 전체 재인덱싱이 자동으로 시작되지 않습니다. 배너와 따라잡기 버튼을 사용하세요.
• 작업이 실행되는 중에 N을 변경해도 해당 작업의 기간은 바뀌지 않습니다. 새 범위를 적용하려면 작업을 중단하고 새 작업을 시작하세요.

1. System Console > Plugins > Agents > Embedding Search로 이동합니다

2. 재인덱싱 컨트롤을 사용하여 다음을 수행합니다.

   • 초기 설정 중 인덱싱 진행 상황을 모니터링합니다.
   • 임베딩 제공업체, 모델, 차원, 벡터 정밀도를 변경하거나 N에 대한 첫 과거 데이터 기준선이 필요할 때 전체 재인덱싱을 실행합니다.
   • N을 늘린 후, 또는 마지막으로 성공한 인덱싱 이후 생성되었지만 아직 저장되지 않은 게시물을 인덱싱하기 위해 따라잡기를 실행합니다.
   • HNSW M을 변경할 때 벡터 인덱스 재빌드를 실행합니다(빌드 중에는 검색을 사용할 수 없음).
   • 인덱싱 상태를 확인합니다.

OpenTelemetry 트레이싱#

플러그인은 요청 지연 시간, LLM 호출 성능, 도구 실행, 오류 진단에 대한 가시성을 제공하기 위해 OpenTelemetry를 통한 분산 트레이싱을 지원합니다.

트레이싱 대상#

활성화하면 플러그인은 다음에 대한 스팬을 생성합니다.

• HTTP 요청: 플러그인에 대한 모든 API 호출이며, 메서드, 경로, 상태 코드를 포함합니다(otelgin 미들웨어를 통해)
• LLM 완성: 제공업체, 모델, 작업 유형, 스트리밍 상태, 입력/출력 토큰 수, 오류
• 도구 실행: 기본 제공 도구와 MCP 도구 모두에 대한 도구 이름, ID, 확인 상태, 오류
• MCP 도구 호출: 원격 MCP 서버와 도구 이름
• 시맨틱 검색: 검색 쿼리와 결과 검색
• 웹 검색: Brave 및 Google 검색 API 호출
• 게시물 스트리밍: 게시물로 LLM 응답을 스트리밍하는 소요 시간과 컨텍스트

스팬은 요청 흐름을 따르는 부모-자식 계층 구조로 구성되므로, 사용자 메시지 하나가 다음과 같은 트레이스를 생성합니다.

HTTP POST /post/:postid/react
  └── process user request
       ├── llm chat completion (provider=openai, model=gpt-4o, tokens=150/42)
       ├── resolve tool (tool=web_search)
       └── stream to post

트레이싱 활성화#

플러그인은 System Console의 트레이스 출력에서 구성할 수 있는 세 가지 트레이스 출력 모드를 제공합니다.

• 끔 — 트레이싱이 비활성화되며 오버헤드가 전혀 없습니다.
• 서버 로그 — 완료된 스팬이 표준 플러그인 로거를 통해 Mattermost 서버 로그에 기록됩니다. 수집기가 필요 없으므로 Tempo, Jaeger 또는 다른 OTLP 백엔드를 운영하지 않는 경우 이 모드를 선택하세요.
• OTLP 엔드포인트 — 스팬이 OpenTelemetry 엔드포인트에 구성된 엔드포인트(예: localhost:4317)로 OTLP gRPC를 통해 내보내집니다. Grafana Tempo나 Jaeger 같은 백엔드를 사용한 전체 분산 트레이싱에 이 모드를 사용하세요.

이 설정은 플러그인 구성 JSON에서 직접 구성할 수도 있습니다.

{
  "telemetryOutput": "otlp",
  "openTelemetryEndpoint": "your-collector:4317"
}

telemetryOutput의 유효한 값은 off, logs, otlp입니다. off로 설정하거나 생략하면 플러그인은 오버헤드가 없는 no-op 트레이서를 사용합니다. openTelemetryEndpoint 필드는 모드가 otlp일 때만 참조됩니다.

Grafana Tempo를 사용한 로컬 개발#

로컬 개발과 디버깅에는 포함된 Docker Compose 파일을 사용하여 Grafana Tempo와 Grafana를 실행하세요.

docker compose -f dev/docker-compose.otel.yml up -d

이렇게 하면 다음이 시작됩니다.

• OTLP gRPC가 포트 4317, OTLP HTTP가 포트 4318인 Tempo
• Tempo 데이터 소스가 사전 프로비저닝된 http://localhost:3001의 Grafana(익명 Admin, 로그인 불필요)

엔드포인트를 localhost:4317로 플러그인을 구성한 다음 봇과 상호작용하세요. Grafana → Explore → Tempo를 열고 서비스 이름 mattermost-ai-agents로 검색하거나 트레이스 ID를 직접 붙여 넣으세요.

Grafana는 Mattermost의 웹앱 개발 서버나 mattermost-server 빌드/docker-compose 스택과 충돌하지 않도록 기본 포트 3000이 아닌 포트 3001에 매핑됩니다.

스택을 중지하려면 다음을 실행하세요.

docker compose -f dev/docker-compose.otel.yml down

누적된 트레이스도 함께 삭제하려면 -v를 추가하세요.

프로덕션 배포#

프로덕션에서는 기존 OpenTelemetry Collector나 백엔드로 직접 트레이스를 전송하세요.

• OpenTelemetry Collector: 엔드포인트가 수집기의 OTLP gRPC 주소를 가리키도록 합니다. 그러면 수집기가 Jaeger, Zipkin, Datadog, Grafana Tempo, AWS X-Ray 또는 지원되는 다른 백엔드로 내보낼 수 있습니다.
• 직접 내보내기: OTLP gRPC를 지원하는 백엔드(예: tempo:4317의 Grafana Tempo)로 엔드포인트가 직접 향하도록 합니다.

연결은 현재 안전하지 않은(비 TLS) gRPC를 사용합니다. TLS 종단 엔드포인트의 경우 TLS가 구성된 OpenTelemetry Collector를 거쳐 라우팅하세요.

커스텀 스팬 속성#

트레이스에는 필터링과 분석을 위한 다음 시맨틱 속성이 포함됩니다. 캐시된 토큰, 추론 토큰, 비용 속성은 제공업체가 0이 아닌 값을 보고하는 경우에만 추가됩니다.

감사 로깅#

플러그인은 상태를 변경하는 모든 작업에 대해 서버 감사 레코드를 생성합니다. 여기에는 구성 저장, 관리자 재인덱싱 및 MCP 캐시 작업, 에이전트 및 커스텀 프롬프트 CRUD, MCP OAuth 자격 증명 부여/해지, 사용자별 MCP 환경설정, 플러그인 간 MCP 서버 등록, 채널 내 도구 호출 승인, 외부 클라이언트에 대한 MCP 세션 권한 부여가 포함됩니다.

레코드는 행위자(사용자 ID, 세션, IP), 이벤트, 요청 경로, 결과(실패와 권한 거부를 HTTP 상태 코드로 포함), 트레이스로 전환해 볼 수 있는 OpenTelemetry trace_id, 위 표와 같은 속성 이름을 사용하는 영향받은 객체의 식별자를 나타냅니다. 레코드에는 프롬프트 콘텐츠, 대화 또는 채널 콘텐츠, 도구 인수나 결과, 구성 값, 자유 형식 오류 텍스트가 포함되지 않습니다. 구성 저장은 변경된 최상위 섹션만 기록하며, 실패 세부 정보는 서버 로그에 남습니다(타임스탬프, 행위자 또는 trace_id로 대조하세요).

플러그인 측 토글은 없습니다. 레코드는 항상 서버로 전달되며, 보존 여부는 전적으로 서버의 감사 로깅 구성(System Console → Compliance 또는 ExperimentalAuditSettings)에 따라 결정됩니다.

백업 및 복원#

플러그인은 에이전트 데이터를 플러그인 구성과 플러그인 데이터베이스 테이블 모두에 저장합니다. 백업하려면 다음을 수행하세요.

1. 정기 Mattermost 백업에 플러그인 구성 데이터가 포함되어 있는지 확인합니다.
2. 플러그인 데이터베이스 테이블을 일반 백업 및 복원 프로세스에 포함합니다. 특히 다음 테이블이 중요합니다.
   • Agents 페이지에서 생성하거나 관리하는 에이전트를 위한 Agents_UserAgents
   • 커스텀 프롬프트 템플릿과 프롬프트 고정을 위한 LLM_CustomPrompts 및 LLM_CustomPromptPins
3. 대규모 배포의 경우 인덱싱된 벡터 데이터를 별도로 백업하는 것을 고려하세요.

플러그인 구성만 복원해서는 Agents 페이지에서 관리하는 에이전트를 복원하기에 충분하지 않습니다.

구성 형식#

플러그인은 서비스 기반 아키텍처를 사용합니다.

• PluginSettings.Plugins["mattermost-ai"]["config"]는 defaultBotName을 포함하여 플러그인 전체 설정과 AI 서비스 구성을 저장합니다
• 에이전트는 Agents_UserAgents 테이블에 별도로 저장됩니다

이렇게 분리하면 여러 에이전트가 같은 LLM 서비스 구성을 공유하면서도 에이전트 라이프사이클과 액세스 데이터를 config.bots에서 분리해 둘 수 있습니다.

구성 구조:

{
  "config": {
    "services": [
      {
        "id": "k3g8sdb1ntbibnyt8u5jmqhc7w",
        "name": "OpenAI Service",
        "type": "openai",
        "apiKey": "sk-...",
        "defaultModel": "gpt-4o",
        "fallbackServiceID": "z9d4meq7jtrx5nch1u8kwsoa3e"
      }
    ],
    "defaultBotName": "ai"
  }
}

서비스 ID는 Mattermost 방식의 26자 ID입니다. 이 형식이 도입되기 전에 생성된 구성은 UUID를 사용했으며, 해당 ID는 업그레이드 시 한 번 다시 작성됩니다. 따라서 UUID 서비스 ID를 하드코딩한 외부 자동화는 새 ID를 가져오기 위해 GET /plugins/mattermost-ai/admin/config를 다시 읽어야 합니다.

지원되는 서비스 유형: openai, anthropic, azure, openaicompatible, asage, cohere, north, mistral, scale

레거시 형식: config.bots에 봇을 저장했거나 봇 안에 서비스 객체를 내장한 이전 구성은 플러그인을 시작할 때 마이그레이션됩니다. 레거시 봇 마이그레이션이 완료되면 봇이 중복 등록되지 않도록 저장된 config.bots 항목이 제거됩니다.

문제 해결#

로깅#

향상된 로깅은 문제를 진단하는 데 도움이 됩니다.

1. 구조화된 로깅 필드 plugin_ai가 mattermost-ai로 설정된 항목이 있는지 서버 로그를 확인합니다.
2. 모든 LLM 상호작용의 상세한 요청/응답 정보를 보려면 플러그인 구성에서 LLM 트레이스를 활성화합니다.
3. 추가 진단 정보를 보려면 플러그인 구성에서 디버그 로깅을 활성화합니다.
4. 프로덕션 환경에서는 문제 해결 후 로그 양을 줄이기 위해 디버그 로깅과 LLM 트레이스를 비활성화합니다.

도구 실행 실패#

도구 호출이 실패하더라도 에이전트가 항상 즉시 중단되는 것은 아닙니다. 에이전트는 복구하거나, 실패를 설명하거나, 해당 도구 없이 답변할 수 있도록 후속 모델 턴을 계속 진행할 수 있습니다.

끝없는 재시도를 방지하기 위해 플러그인은 연속 3회의 도구 시도 실패라는 제한을 적용합니다. 그 이후에는 해당 시퀀스에서 더 이상 도구 호출이 이루어지지 않으며, 모델은 가장 최근 오류를 설명하고 사용자에게 안내나 권한, 식별자, 구성 세부 정보 같은 누락된 정보를 요청하도록 지시받습니다.

사용자가 도구 실패 반복을 보고하면 LLM 트레이스와 디버그 로깅을 사용하여 도구 오류와 업스트림 응답을 확인하세요. 또한 API 키, 엔드포인트, MCP 연결, 서드파티 인가와 같은 연동 구성을 확인하고, 사용자가 도구가 대상으로 하는 기반 Mattermost 리소스에 접근할 수 있는지 확인하세요.

연동#

연동은 기본적으로 다이렉트 메시지에서 사용할 수 있습니다. 실험적 설정인 채널 멘션 도구 호출 활성화를 켜면 공개 채널에서 에이전트를 @멘션하여 그곳에서도 도구 호출을 허용할 수 있습니다. 공개 및 비공개 채널에서의 네이티브 제공업체 웹 검색은 채널에서 네이티브 웹 검색 허용으로 별도로 제어됩니다.

에이전트의 파일 생성#

기본 제공 CreateFile 도구를 사용하면 에이전트가 자신의 응답에 첨부되는 텍스트 파일을 생성할 수 있습니다. 이 도구는 동적 도구 로딩 메타 도구와 마찬가지로 승인 프롬프트 없이 자동으로 실행됩니다. 유일한 효과가 에이전트 자신의 응답에 파일을 첨부하는 것이기 때문이며, 사용자에게는 해결된(자동 승인된) 도구 카드가 표시됩니다. 내장 및 외부 MCP 게시 도구(create_post, dm, group_message)도 인라인 files 매개변수를 허용하며, 해당 도구에 구성된 승인 정책에 따라 수행 사용자로서 첨부 파일을 생성합니다. 채널에서는 이 모든 기능의 사용 가능 여부가 기존 채널 멘션 도구 호출 활성화 설정을 따릅니다.

Model Context Protocol(MCP) 연동#

Model Context Protocol(MCP) 연동을 사용하면 Agents가 내장 Mattermost 도구, 호환되는 Mattermost 플러그인이 등록한 MCP 서버, 선택적 원격 서버를 포함하여 MCP 서버가 노출하는 도구를 사용할 수 있습니다.

MCP 클라이언트와 내장 Mattermost MCP 서버는 항상 활성화되어 있습니다. 관리자는 System Console의 MCP UI에서 원격 MCP 서버와 연결 타임아웃을 관리합니다. 도구 탭에는 플러그인이 등록한 MCP 서버도 표시되며, 관리자는 여기에서 각 플러그인 서버를 활성화하거나 비활성화하고 도구별 활성화 상태와 승인 정책을 설정할 수 있습니다. 에이전트 수준의 MCP 접근은 각 에이전트의 MCP 탭에서 별도로 구성합니다.

원격 및 외부 MCP 서버는 Enterprise 이상에서 사용할 수 있습니다(라이선스 요구 사항 참조). 그보다 낮은 수준에서는 저장된 원격 서버가 계속 표시되지만 추가하거나 활성화할 수 없으며, 원격 서버의 도구는 에이전트에서 사용할 수 없습니다. 내장 Mattermost MCP 도구는 모든 플랜에서 사용할 수 있습니다(읽기 전용 도구는 모든 수준에서, 상태를 변경하는 도구는 Enterprise 이상에서).

구성#

1. System Console > Plugins > Agents > Model Context Protocol (MCP)로 이동합니다.

2. 구성 탭에서 다음을 수행할 수 있습니다.

   • Mattermost MCP 서버(HTTP) 활성화: 외부 MCP 클라이언트를 위한 선택적 HTTP 엔드포인트입니다. Mattermost MCP 서버를 참조하세요.
   • 연결 유휴 타임아웃(분): 비활성 사용자 MCP 연결의 타임아웃입니다(기본값: 30분).
   • URL, 커스텀 헤더, OAuth 클라이언트 설정, 서비스 계정 헤더, 서버별 활성화를 포함한 원격 MCP 서버.
   • 기본 제공 및 플러그인 서버: 내장 Mattermost MCP 서버와 현재 등록된 플러그인 MCP 서버를 보여주는 읽기 전용 카드입니다. 각 카드의 액세스 정책 섹션을 사용하여 해당 서버의 도구를 사용할 수 있는 사용자를 제한하세요(속성 기반 접근 제어(ABAC) 참조). 기본 제공 서버를 거부하면 해당 사용자에게서 제품 내 Mattermost 도구 대부분이 제거됩니다. 플러그인 활성화와 도구별 승인은 도구 탭에 남아 있습니다.

3. 도구 탭을 사용하여 검색된 도구를 검토하고 각 도구의 활성화 상태와 승인 정책을 설정합니다. 도구 행을 펼쳐 동적 도구 로딩 검색용 선택적 검색 설명 재정의를 추가하세요. 이는 에이전트가 도구를 찾는 데 도움이 되지만 로드 후 전송되는 도구 스키마는 변경하지 않습니다. 플러그인이 등록한 MCP 서버는 이 탭에서 별도의 플러그인 행으로 표시됩니다.

4. Agents 페이지에서 에이전트를 생성하거나 편집할 때 MCP 탭을 사용하여 해당 에이전트가 모든 MCP 도구를 자동으로 사용할지 선택한 도구 집합만 사용할지, 그리고 MCP 도구 스키마를 동적으로 로드할지 미리 노출할지를 선택합니다.

에이전트의 MCP 접근은 관리자 도구 정책, MCP 서버 액세스 정책(구성된 경우), 에이전트의 MCP 허용 목록 또는 모든 MCP 도구 자동 활성화 설정, 사용자가 비활성화한 제공업체 환경설정, 현재 요청에 대한 컨텍스트 제한에 따라 필터링됩니다. 서비스 계정 인증을 사용하는 에이전트의 경우 사용자가 비활성화한 제공업체 환경설정은 적용되지 않습니다.

현재 사용자가 OAuth 기반 MCP 서버를 연결하거나 연결 해제하면 도구 탭이 자동으로 새로 고쳐집니다. MCP OAuth 연결은 사용자별이므로 이 실시간 새로 고침은 연결 또는 연결 해제 작업을 완료한 사용자에게만 적용됩니다.

System Console에서 MCP 전체를 비활성화할 수는 없습니다. 접근을 제한하려면 도구 탭에서 개별 도구를 비활성화하거나 정책을 변경하세요.

MCP 서버 추가#

1. 구성 탭에서 원격 MCP 서버 추가를 선택하여 새 서버를 구성합니다.

2. 서버 설정을 구성합니다.

   • 서버 URL: MCP 서버의 엔드포인트 URL입니다. 서버의 최종 주소를 사용하세요. 자격 증명이 다른 호스트로 유출되지 않도록 다른 출처로의 리디렉션(http에서 https로의 업그레이드 포함)은 거부됩니다.
   • 커스텀 헤더: MCP 서버에 필요한 추가 헤더입니다(선택 사항).
   • 서비스 계정 인증: 인증에 서비스 계정 사용이 활성화된 에이전트가 사용자별 OAuth 대신 사용하는 정적 헤더입니다(선택 사항). 서비스 계정 인증을 참조하세요.
   • 서버 이름: 서버를 설명하는 이름입니다(제공하지 않으면 자동 생성됨).

3. 저장을 선택하여 서버를 추가합니다.

플러그인이 등록한 MCP 서버#

호환되는 Mattermost 플러그인은 Agents에 MCP 서버를 등록할 수 있습니다. 도구 탭에서 등록된 각 플러그인 서버는 별도의 플러그인 행으로 표시되며, 관리자는 여기에서 플러그인 서버 전체를 활성화하거나 비활성화하고 도구별 승인 정책을 구성할 수 있습니다. 플러그인 도구 이름은 원시 와이어 형식 이름 대신 더 알아보기 쉬운 형태로 표시됩니다.

플러그인 서버의 액세스 정책은 구성 탭의 기본 제공 및 플러그인 서버 아래에서 작성합니다. 정책 식별은 소스 플러그인 ID를 키로 하므로, 등록 해제/재등록과 경로 변경 후에도 정책이 유지됩니다. 플러그인이 등록을 해제해도 정책은 자동으로 삭제되지 않으며, 같은 플러그인이 다시 등록하면 휴면 상태의 정책이 다시 연결됩니다.

이러한 관리자 소유 설정(활성화, 도구별 승인, 액세스 정책)은 플러그인 재등록과 재시작 후에도 유지됩니다.

소스 플러그인이 플러그인 서버의 이름, 경로, 외부 노출 대상 여부를 제어합니다. 관리자는 Agents UI에서 외부 노출 플래그를 구성하지 않습니다.

플러그인 서버가 활성화되어 있고 소스 플러그인이 외부 노출 대상으로 표시한 경우, 해당 서버의 활성화된 도구를 외부 Mattermost MCP HTTP 엔드포인트에 추가할 수 있습니다. 도구별 관리자 정책은 그곳에서도 해당 도구에 적용됩니다.

플러그인이 등록한 MCP 서버로 프록시되는 도구 호출은 인증된 Mattermost 사용자 컨텍스트를 소스 플러그인까지 전달하므로 사용자 범위 권한이 계속 적용됩니다.

에이전트용 OAuth 기반 서버 구성#

Agents 페이지에서 에이전트를 생성하거나 편집할 때, 전체 페이지 에이전트 편집기의 MCP 탭에는 해당 에이전트가 사용할 수 있는 MCP 서버가 나열됩니다.

• 사용자별 인증을 사용하는 에이전트의 경우, OAuth 기반 서버가 아직 내 계정에 연결되지 않았다면 해당 행에 연결 버튼이 표시되어 편집기를 떠나지 않고도 제공업체 로그인 흐름을 완료할 수 있습니다.
• 인증에 서비스 계정 사용이 활성화된 에이전트의 경우, 이 탭에는 내 개인 연결이 아니라 해당 에이전트의 서비스 계정 카탈로그가 표시됩니다. 서비스 계정 자격 증명만 있는 서버는 해당 자격 증명이 작동할 때 연결됨으로 표시되며 연결은 표시되지 않습니다. 서비스 계정 자격 증명이 없는 서버는 서비스 계정 자격 증명 없음으로 표시되며 에이전트에서 제외됩니다.

MCP 탭은 연결하거나 연결 해제한 후 자동으로 새로 고쳐지며 서비스 계정 인증을 전환할 때 다시 로드되므로, 업데이트된 서버 상태를 확인하기 위해 탭을 다시 열 필요가 없습니다.

연결이 해제된 OAuth 기반 서버가 현재 노출하는 도구가 없더라도 에이전트를 구성하는 동안 해당 서버를 켤 수 있습니다. 이 상태에서 에이전트를 저장하면 사용자가 해당 제공업체에 연결한 후 그 서버가 노출하는 모든 도구에 대한 접근 권한이 에이전트에 부여됩니다.

모든 MCP 도구 자동 활성화 옵션은 여전히 가장 포괄적인 설정입니다. 활성화하면 에이전트가 현재 사용 가능한 모든 MCP 도구와 나중에 추가되는 MCP 도구를 사용할 수 있습니다.

에이전트에 서버나 도구를 활성화하면 에이전트가 사용할 수 있는 항목을 제어하지만 도구 승인 정책을 우회하지는 않습니다. 도구 실행은 계속 도구 탭에 구성된 정책과 각 사용자의 Mattermost 및 제공업체 권한을 따릅니다.

서비스 계정 인증#

기본적으로 MCP 도구 호출은 에이전트를 트리거한 사용자의 자격 증명으로 실행됩니다. 외부 MCP 서버에서는 사용자별 OAuth를, 내장 Mattermost 도구에서는 요청한 사용자 본인의 신원을 사용합니다. 대신 에이전트를 서비스 계정 인증으로 전환할 수 있으며, 이 경우 외부 MCP 서버는 관리자가 구성한 공유 자격 증명을 사용합니다. 내장 Mattermost 도구와 플러그인 도구는 계속 요청한 사용자로 실행됩니다.

설정 방법은 다음과 같습니다.

1. System Console > Plugins > Agents > Model Context Protocol (MCP)로 이동하여 구성 탭에서 원격 MCP 서버를 열고, 서비스 계정 인증 섹션에 서비스 계정 에이전트로부터 서버가 수신해야 하는 정적 헤더를 추가합니다. 헤더 이름과 값은 별도의 필드에 입력합니다. 예를 들어 이름은 Authorization, 값은 Bearer <token> 또는 Basic <base64>로 하거나, X-API-KEY 같은 커스텀 이름을 사용합니다. 값에 헤더 이름을 반복하지 마세요. 이름이나 값이 비어 있는 행은 무시되므로 모든 항목이 비어 있는 서버는 서비스 계정 자격 증명이 없는 것으로 간주됩니다. 저장을 선택합니다.
2. 에이전트의 MCP 탭(Agents 페이지)에서 인증에 서비스 계정 사용을 켭니다. 시스템 관리자만 이 설정을 켤 수 있습니다. 이 설정이 활성화되어 있는 동안에도 관리자는 민감하지 않은 구성을 계속 편집할 수 있으며, 액세스 및 MCP 권한 부여(자동 활성화 포함)는 시스템 관리자 전용으로 유지됩니다. 편집 가능한 항목과 잠긴 항목을 참조하세요. 에이전트를 관리할 수 있는 사용자는 누구나 이 설정을 끄거나 에이전트를 삭제할 수 있습니다.

에이전트 설정은 전부 아니면 전무 방식입니다.

• 외부 MCP 서버: 연결은 사용자별 OAuth 대신 서버의 서비스 계정 헤더를 전송합니다. 서버의 커스텀 헤더는 두 모드 모두에서 계속 전송되며, 둘 다 같은 헤더를 정의하면 서비스 계정 값이 우선합니다. 서비스 계정 헤더가 없는 서버는 이 에이전트에서 완전히 제외되며, 안전 실패(fail closed) 방식으로 어떤 사용자의 개인 OAuth 연결로도 폴백하지 않습니다. 개인 접근과 서비스 계정 접근을 함께 사용하려면 에이전트 두 개나 별도의 MCP 서버 항목을 사용하세요.
• 내장 Mattermost 도구와 플러그인이 등록한 MCP 서버: 도구 호출은 사용자별 모드와 마찬가지로 요청한 사용자로 실행됩니다. 해당 사용자의 채널 구성원 자격과 Mattermost 권한이 접근 경계이며, 게시물 읽기, 검색, 채널 구성원 목록 조회는 해당 사용자가 읽을 수 있는 내용을 반환합니다.
• 사용자에게는 이 에이전트를 위해 계정을 연결하라는 안내가 표시되지 않으며, 사용자별 도구 제공업체 환경설정은 적용되지 않고, Agents RHS의 도구 팝오버는 숨겨집니다.
• 도구 승인은 변경되지 않습니다. 에이전트를 트리거한 사람이 구성된 도구 정책에 따라 도구 호출을 계속 승인하거나 거부합니다. 멀티플레이어 도구 호출을 참조하세요.

Warning: 서비스 계정 인증은 외부 MCP 서버에서 권한을 평탄화합니다. 그곳에서는 에이전트를 사용할 수 있는 모든 사용자가 에이전트의 공유 접근 권한으로 행동합니다. 에이전트의 액세스 탭에서 에이전트를 사용할 수 있는 사용자를 제한하고, 통합마다 전용 서비스 계정(및 MCP 서버 항목)을 사용하며 에이전트에 필요한 최소 권한으로 범위를 지정하세요. 외부 시스템은 에이전트의 작업을 이를 트리거한 Mattermost 사용자가 아니라 서비스 계정의 작업으로 귀속합니다. 이를 대조하려면 토큰 사용량 추적을 활성화하세요. 각 레코드에는 트리거한 사용자(user_id), 수행 신원(acting_user_id), 인증 모드(tool_auth_mode)가 담깁니다. Mattermost 및 플러그인 도구는 계속 각 요청 사용자 본인의 권한으로 실행됩니다. 헤더 값은 서버의 다른 자격 증명과 마찬가지로 플러그인 구성에 저장되며 시스템 관리자에게 표시됩니다.

서비스 계정 인증은 원격 및 외부 MCP 서버와 마찬가지로 Enterprise 이상에서 사용할 수 있습니다(라이선스 요구 사항 참조). 그보다 낮은 수준에서는 서비스 계정 헤더 구성을 추가할 수 없으며 에이전트 설정은 도구 호출 인증 방식을 변경하지 않습니다.

MCP 동적 도구 로딩#

에이전트의 MCP 동적 도구 로딩 설정이 활성화되어 있으면 모델은 모든 전체 MCP 도구 스키마를 한꺼번에 받지 않습니다. 대신 search_tools와 load_tool 메타 도구와, 해당 요청에 사용할 수 있는 사전 로드되었거나 내부적인 도구를 봅니다.

search_tools는 이름과 요약이 포함된 후보 도구를 최대 8개 반환합니다. load_tool은 정확한 이름으로 도구 하나의 전체 스키마를 로드합니다. 비즈니스 MCP 도구는 실행하기 전에 로드해야 하며, 로드되지 않은 MCP 도구를 실행하려는 시도는 먼저 load_tool을 호출하라는 안내와 함께 거부됩니다.

도구가 성공적으로 로드되면 대화의 나머지 동안 계속 사용할 수 있습니다. 이후 턴에서는 로드된 도구가 여전히 인가되어 있고 사용 가능한 경우 보존된 대화 기록에서 복원됩니다.

search_tools와 load_tool 메타 도구는 승인 없이 자동으로 실행됩니다. 로드된 비즈니스 도구는 여전히 구성된 승인 정책과 사용자의 Mattermost 및 제공업체 권한을 따르며, 서비스 계정 인증을 사용하는 에이전트의 경우 외부 MCP 서버에서는 서비스 계정 자격 증명을, 내장 및 플러그인 도구에서는 요청한 사용자의 Mattermost 권한을 따릅니다.

동적 로딩은 일반 에이전트 대화 턴에 적용됩니다. Bridge 연동과 직접 도구 카탈로그 요청은 여전히 구체적인 도구 스키마를 직접 요청할 수 있습니다.

관리#

• 연결 관리: 시스템이 MCP 서버에 대한 사용자 연결을 자동으로 관리합니다
• 유휴 정리: 비활성 클라이언트 연결은 구성된 타임아웃 후 자동으로 닫힙니다
• 사용자별 연결: 보안과 격리를 위해 각 사용자는 MCP 서버에 대한 자신만의 연결을 가집니다. 서비스 계정 인증을 사용하는 에이전트는 외부 MCP 서버에 대해 에이전트당 하나의 원격 연결(에이전트의 봇 계정을 키로 함)을 공유하며, 내장 Mattermost 및 플러그인 연결은 요청한 사용자별로 유지됩니다
• 도구 정책: 도구 탭을 사용하여 개별 도구를 허용하거나, 승인을 요구하거나, 비활성화하고, 동적 도구 로딩 검색에 사용되는 선택적 검색 설명 재정의를 추가합니다
• 에이전트 범위 지정: RHS 도구 팝오버에는 선택한 에이전트에 허용된 MCP 제공업체만 표시되며, 서비스 계정 인증을 사용하는 에이전트에서는 완전히 숨겨집니다(관리할 사용자별 원격 연결이나 환경설정이 없으며, 내장 Mattermost 및 플러그인 연결은 계속 요청한 사용자로 실행됨). 도구 사용은 여전히 관리자 도구 정책과 사용자의 Mattermost 권한을 따릅니다

OAuth 기반 MCP 서버#

일부 MCP 서버는 Mattermost 사용자별 OAuth를 요구합니다. 이러한 서버에 대해 플러그인은 Agents 웹앱에 needsOAuth와 authURL을 노출하므로, UI가 인가가 필요한 시점과 흐름을 시작할 위치를 표시할 수 있습니다. 웹앱은 플러그인 경로 GET /plugins/mattermost-ai/mcp/oauth/<server name>/start를 통해 OAuth를 시작하며, DELETE /plugins/mattermost-ai/mcp/oauth/<server name>으로 현재 사용자의 저장된 토큰을 삭제할 수 있습니다.

Agents 패널(웹 및 데스크톱): Agents 오른쪽 사이드바에서 새 채팅을 시작하고 도구를 엽니다. OAuth 기반 서버는 로그인한 사용자가 인증되지 않은 경우 연결을, OAuth 세션이 적용되는 경우 연결 해제를 표시합니다.

System Console(관리자 도구 구성): System Console > Plugins > Agents > MCP Servers에서 OAuth 기반 서버를 펼치면, 해당 서버의 도구 목록을 가져오고 도구별 승인 정책을 구성하려면 인증해야 한다는 안내가 표시됩니다. 이 로그인은 내 관리자 계정에만 적용됩니다. 관리자가 System Console에서 연결한 후에도 각 최종 사용자는 별도로 인증해야 합니다.

대화: 플러그인은 더 이상 MCP OAuth를 안내하기 위해 채널이나 스레드에 임시 메시지를 게시하지 않습니다. 사용자는 Agents 웹앱의 도구 메뉴를 사용하여 연결 상태를 확인하고 연결 또는 연결 해제를 실행해야 합니다.

모바일 및 기타 클라이언트: MCP OAuth는 모바일 앱이나 Agents 웹앱을 사용하지 않는 다른 클라이언트에서 시작되지 않습니다. OAuth 기반 MCP 서버를 연결하려면 사용자가 Mattermost 웹 또는 데스크톱을 사용해야 합니다.

커스텀 MCP OAuth 설정: OAuth 시작 URL에 resource_metadata 쿼리 매개변수가 포함된 경우, 해당 매개변수의 출처가 구성된 MCP 서버 서버 URL의 출처와 일치할 때만 허용됩니다. 이는 검색 중 교차 출처 메타데이터 주입을 방지합니다.

Atlassian MCP 서버 인가#

사용자가 Atlassian MCP 서버에 연결할 때 조직 관리자가 Mattermost 도메인을 인가해야 한다는 인가 오류가 발생할 수 있습니다. 이 구성은 Atlassian의 관리 콘솔에서 완료해야 합니다.

Mattermost 도메인을 인가하려면:

1. admin.atlassian.com으로 이동하여 조직을 선택합니다.
2. Apps > AI settings > Rovo MCP server로 이동합니다.
3. 도메인 추가를 선택하고 경로 와일드카드를 포함한 Mattermost 도메인을 입력합니다. https://your-instance.mattermost.cloud/**
4. 저장을 선택합니다.

중요: /** 경로 와일드카드는 필수입니다. 도메인 패턴 예시는 다음과 같습니다.

• 단일 인스턴스: https://your-company.mattermost.cloud/**
• 모든 하위 도메인: https://*.mattermost.cloud/**
• 커스텀 도메인: https://chat.yourcompany.com/**

도메인을 추가한 후 사용자가 연결을 다시 시도하기 전에 변경 사항이 전파되도록 1~2분 기다리세요.

문제 해결:

• 조직 관리자(Organization Admin) 권한이 있는지 확인합니다(사이트 관리자(Site Admin)로는 충분하지 않습니다)
• Atlassian 사이트를 소유한 조직을 구성하고 있는지 확인합니다
• 도메인에 https://와 /** 와일드카드가 포함되어 있는지 확인합니다
• 도메인에 오타가 없는지 확인합니다

자세한 내용은 MCP 서버 설정에 대한 Atlassian 문서를 참조하세요.

Note: 기본적으로 플러그인은 AI가 생성한 Markdown 링크(예: JIRA 티켓 링크)를 클릭 가능한 링크로 렌더링하지 않습니다. 피싱 및 데이터 유출 위험을 줄이기 위해 URL은 일반 텍스트로 표시됩니다. 관리자가 AI 생성 링크 렌더링(allowUnsafeLinks)을 활성화하면 AI가 생성한 링크가 클릭 가능해질 수 있으므로, 적절한 신뢰 경계와 보안 완화 조치가 마련된 경우에만 활성화하세요.

Mattermost MCP 서버#

Mattermost MCP 서버를 사용하면 AI 에이전트와 외부 애플리케이션이 Model Context Protocol(MCP)을 통해 Mattermost 인스턴스와 상호작용할 수 있습니다. MCP는 AI 어시스턴트가 메시지를 읽고, 콘텐츠를 검색하고, 게시물을 작성하고, 채널과 팀을 프로그래밍 방식으로 관리할 수 있게 하는 표준화된 프로토콜입니다. 기본 제공 Mattermost 도구는 내장 서버를 통해 Agents에서 항상 사용할 수 있으며, 외부 클라이언트용 선택적 HTTP 엔드포인트는 호환되는 플러그인이 등록한 MCP 서버의 적격 도구도 집계할 수 있습니다.

독립 실행형 MCP 서버(별도 프로세스 / stdio): Mattermost 서버 외부에서 독립 실행형 mattermost-mcp-server 바이너리를 실행하는 것은 개발 및 로컬 사용 전용이며 프로덕션용이 아닙니다. 프로덕션 배포에서는 내장 Mattermost MCP 서버와 이 플러그인에서 지원되는 구성(System Console, 외부 클라이언트용 HTTP 엔드포인트, 아래의 에이전트 MCP 설정)을 사용해야 합니다.

개요#

Mattermost MCP 서버는 다음을 제공합니다.

• 직접적인 Mattermost 연동: AI 에이전트가 표준화된 API를 통해 Mattermost 데이터와 기능에 접근할 수 있습니다
• 보안 및 권한: 모든 작업은 Mattermost의 권한 시스템을 준수하며, 사용자는 열람 권한이 있는 항목에만 접근합니다
• 유연한 배포: Mattermost AI 에이전트용 내장 서버 또는 외부 MCP 클라이언트용 HTTP 서버로 사용할 수 있습니다
• 풍부한 도구 세트: 콘텐츠를 읽고, 검색하고, 생성하기 위한 포괄적인 도구

사용 사례

Mattermost MCP 서버를 사용하면 다음을 할 수 있습니다.

• 채널 요약 자동화: AI 에이전트에게 채널 전반의 활동을 요약하도록 요청하여 자리를 비운 동안의 논의를 따라잡을 수 있습니다.
• 채널 간 업데이트 공유: 에이전트가 여러 채널에 상태 업데이트를 동시에 게시하도록 하여 분산된 팀의 동기화를 유지할 수 있습니다.
• 지능적인 검색: MCP를 사용하는 모든 클라이언트에서 Mattermost 워크스페이스 전체를 검색하여 관련 논의, 결정, 정보를 찾을 수 있습니다.
• 팀 조율: 채널 또는 팀 구성원 목록을 가져와 연락하거나 멘션할 대상을 빠르게 파악할 수 있습니다.
• 워크플로 자동화: 외부 MCP 클라이언트를 사용하여 스탠드업 업데이트 게시, 프로젝트 채널 생성, 중요 이벤트에 대한 팀 알림과 같은 반복 작업을 자동화할 수 있습니다.
• 컨텍스트 인식 지원 이용: AI 에이전트가 응답하거나 조치를 취하기 전에 대화 스레드를 읽어 컨텍스트를 파악할 수 있습니다.

사용 가능한 도구#

기본 제공 Mattermost MCP 서버는 다음 네이티브 Mattermost 도구를 제공합니다.

• read_post: 특정 게시물과 해당 스레드를 읽습니다
• read_channel: 채널의 최근 게시물을 가져옵니다
• search_posts: 선택적 팀/채널 필터로 Mattermost 콘텐츠 전체를 검색합니다
• create_post: 채널에 새 게시물이나 답글을 작성합니다
• dm: 사용자에게 다이렉트 메시지를 보냅니다
• group_message: 그룹 대화에 메시지를 보냅니다
• create_channel: 새 공개 또는 비공개 채널을 생성합니다
• get_channel_info: ID 또는 이름으로 채널 세부 정보를 가져옵니다
• get_team_info: ID 또는 이름으로 팀 세부 정보를 가져옵니다
• search_users: 사용자 이름, 이메일 또는 이름으로 사용자를 찾습니다
• get_channel_members: 채널의 모든 구성원을 나열합니다
• add_channel_member: 채널에 사용자를 추가합니다
• get_user_channels: 현재 사용자가 구성원인 채널을 나열합니다
• get_team_members: 팀의 모든 구성원을 나열합니다
• add_team_member: 팀에 사용자를 추가합니다
• list_agents: 각 에이전트의 ID, 표시 이름, 사용자 이름을 포함하여 현재 사용자가 사용할 수 있는 AI 에이전트(봇)를 나열합니다

플러그인은 Mattermost의 주요 영역을 아우르는 확장된 읽기 및 쓰기 도구 카탈로그도 등록합니다. 플러그인이 동적 도구 로딩을 지원하므로, 에이전트는 모든 스키마를 컨텍스트에 담고 있지 않고 search_tools와 load_tool 메타 도구를 통해 필요할 때 이러한 도구를 찾습니다. 쓰기/파괴적/권한에 민감한 도구는 ⚠로 표시되며 각 사용자의 Mattermost 권한을 따릅니다.

• 게시물 및 메시지: get_post_info, list_pinned_posts, list_saved_posts, ⚠ update_post, ⚠ delete_post, ⚠ pin_post, ⚠ unpin_post, ⚠ save_post, ⚠ acknowledge_post
• 예약 게시물 및 알림: list_scheduled_posts, ⚠ create_scheduled_post, ⚠ update_scheduled_post, ⚠ delete_scheduled_post, ⚠ set_post_reminder
• 리액션 및 이모지: get_post_reactions, list_custom_emoji, search_custom_emoji, ⚠ add_reaction, ⚠ remove_reaction
• 스레드, 멘션 및 읽지 않음: get_threads, get_mentions, get_unread_counts, get_channel_unread, get_posts_around_unread, ⚠ mark_channel_read, ⚠ mark_channels_viewed, ⚠ mark_post_unread, ⚠ set_thread_follow
• 채널: get_channel_stats, get_channel_member_counts, search_channels, list_team_channels, list_archived_channels, ⚠ update_channel, ⚠ archive_channel, ⚠ restore_channel, ⚠ convert_channel_privacy
• 채널 구성원 및 설정: get_channel_member, get_channel_members_by_ids, get_channel_members_by_status, get_user_channel_memberships, get_users_not_in_channel, search_users_in_channel, list_sidebar_categories, ⚠ add_channel_members, ⚠ remove_channel_member, ⚠ set_channel_mute, ⚠ set_channel_favorite, ⚠ update_channel_notify_props
• 채널 북마크: list_channel_bookmarks, ⚠ create_channel_bookmark, ⚠ update_channel_bookmark, ⚠ delete_channel_bookmark
• 사용자 및 프로필: get_me, get_user, get_user_by_username, get_user_by_email, get_users_by_ids, get_users_by_usernames, get_user_stats, get_user_cpa_values, list_cpa_fields, ⚠ update_user
• 상태 및 접속 상태: get_user_status, get_users_statuses, get_user_custom_status, ⚠ set_status, ⚠ set_dnd
• 팀 및 팀 구성원: get_team_member, get_team_stats, get_user_teams, get_users_in_team, get_users_not_in_team, get_new_users_in_team, get_dm_common_teams, search_teams, search_users_in_team, ⚠ add_team_members, ⚠ remove_team_member, ⚠ update_team, ⚠ invite_users_to_team, ⚠ invite_users_to_team_and_channels
• 파일 및 첨부 파일: get_file_info, get_post_files, get_file_link, search_files, ⚠ upload_file
• 연동: get_bot, list_bots, list_incoming_webhooks, list_outgoing_webhooks
• 그룹: get_group_info, list_groups, get_user_groups, get_channel_groups, get_team_groups, get_users_in_group_channels
• 역할 및 권한: get_role, get_channel_moderations, ⚠ update_channel_member_roles, ⚠ update_team_member_roles

이는 Agents 플러그인 자체에 포함된 네이티브 Mattermost 도구입니다. 플러그인이 등록한 MCP 도구는 도구 탭에서 별도로 구성하며 위의 기본 제공 목록에 포함되지 않습니다.

배포#

AI 에이전트용#

내장 Mattermost MCP 서버는 구성된 AI 에이전트에서 자동으로 사용할 수 있습니다. 제품 내 에이전트에서 내장 MCP를 활성화하기 위한 System Console 스위치는 필요하지 않습니다.

System Console > Plugins > Agents > Model Context Protocol (MCP)를 사용하여 원격 MCP 서버를 구성하고, 플러그인이 등록한 MCP 서버를 검토하고, 유휴 타임아웃을 설정하고, 외부 클라이언트용 선택적 HTTP 엔드포인트를 제어하고, 도구별 활성화와 승인 정책을 관리하세요. 그런 다음 Agents 페이지에서 각 에이전트의 MCP 탭을 사용하여 모든 MCP 도구를 자동으로 활성화하거나 해당 에이전트를 특정 도구로 제한합니다.

구성된 에이전트는 자체 MCP 설정, 관리자 도구 정책, 사용자 권한, 필요한 승인 흐름에 따라 이러한 도구를 사용할 수 있습니다.

외부 클라이언트용#

Claude 웹, Claude Code 또는 MCP와 호환되는 다른 애플리케이션과 같은 외부 MCP 클라이언트가 Mattermost 인스턴스와 상호작용하도록 설정할 수 있습니다. 이 HTTP 서버는 Mattermost Agents가 사용하는 항상 켜져 있는 내장 MCP 서버와는 별개입니다.

활성화하면 외부 HTTP 엔드포인트는 기본 제공 Mattermost MCP 도구를 노출합니다. 소스 플러그인이 해당 서버를 외부 노출 대상으로 표시하고 Agents에서 플러그인 서버가 활성화되어 있는 경우, 플러그인이 등록한 MCP 서버의 활성화된 도구도 집계할 수 있습니다.

도구별 관리자 정책은 집계된 플러그인 도구에 적용됩니다. 프록시된 플러그인 도구 호출은 인증된 Mattermost 사용자 컨텍스트를 소스 플러그인까지 전달하므로, 소스 플러그인이 사용자 범위 권한을 계속 적용할 수 있습니다.

노출된 플러그인 도구 이름이 기본 제공 Mattermost 도구 또는 노출된 다른 플러그인 도구와 충돌하면, 충돌하는 플러그인 도구는 외부 엔드포인트에서 제외됩니다. 이러한 충돌은 로그에 기록됩니다.

요구 사항:

• Mattermost Server v11.2 이상
• 유효한 인증 방법(OAuth 또는 개인 액세스 토큰)

참고: 서버는 스트리밍 가능한 HTTP 전송을 사용하며 기존 Server-Sent Events(SSE) 전송은 지원하지 않습니다. 외부 클라이언트는 /mcp 엔드포인트에서 제공되는 스트리밍 가능한 HTTP 전송을 사용해야 합니다.

외부 MCP 클라이언트를 활성화하려면 다음을 수행하세요.

1. System Console > Plugins > Agents > Model Context Protocol (MCP)로 이동합니다
2. Mattermost MCP 서버(HTTP) 활성화를 True로 설정합니다. MCP 서버는 다음 주소에서 사용할 수 있습니다. https://your-mattermost-server/plugins/mattermost-ai/mcp-server/mcp

인증:

OAuth 2.0

MCP 서버는 수동 및 자동 클라이언트 등록 모두에서 OAuth 2.0 인증을 지원합니다.

사전 요구 사항:

• System Console > Integrations > Integration Management에서 OAuth 2.0 서비스 제공자를 활성화합니다.
  • OAuth 2.0 서비스 제공자 활성화를 True로 설정합니다
  • 자동 클라이언트 등록을 사용하려면 OAuth 2.0 동적 클라이언트 등록 활성화를 True로 설정합니다(참고: DCR은 보호되지 않는 엔드포인트이므로 공개적으로 접근할 수 있고 인증이 필요하지 않습니다. 이 기능이 활성화되어 있으면 누구나 OAuth 클라이언트를 등록할 수 있습니다. 보안 고려 사항은 OAuth 2.0 문서를 참조하세요.)

클라이언트 등록 방법:

• 동적 클라이언트 등록(DCR/RFC 7591): 외부 클라이언트가 수동 설정 없이 자동으로 등록하고 자격 증명을 얻을 수 있습니다.
• 수동 등록: 제품 메뉴 > Integrations > OAuth 2.0 Applications를 통해 OAuth 애플리케이션을 생성합니다. 자세한 내용은 OAuth 2.0 문서를 참조하세요.

추가 세부 정보:

• 공개 클라이언트(예: 데스크톱 애플리케이션)와 기밀 클라이언트(예: 서버 애플리케이션)를 모두 지원합니다
• 표준 Mattermost OAuth 흐름을 통한 인가
• OAuth 메타데이터 엔드포인트:
  • 보호된 리소스 메타데이터: https://your-mattermost-server/plugins/mattermost-ai/mcp-server/.well-known/oauth-protected-resource
  • 인가 서버 메타데이터: https://your-mattermost-server/.well-known/oauth-authorization-server

개인 액세스 토큰

Mattermost 개인 액세스 토큰(PAT)을 사용하여 인증할 수 있습니다.

1. Mattermost에서 개인 액세스 토큰을 생성합니다(사용자 설정 > 보안 > 개인 액세스 토큰).
2. PAT를 사용한 Bearer 토큰 인증을 사용하도록 MCP 클라이언트를 구성합니다.

라이선스 요구 사항#

플러그인은 네 가지 라이선스 수준, 즉 Free(라이선스 없음), Professional, Enterprise, Enterprise Advanced를 구분합니다. 각 수준에는 그보다 낮은 수준에서 사용할 수 있는 모든 기능이 포함됩니다. Entry 라이선스는 Enterprise와 동일하게 동작합니다. 개발 서버(EnableDeveloper와 EnableTesting이 모두 켜진 경우)는 모든 기능을 실행합니다.

각 행이 적용되는 방식은 다음과 같습니다.

• AI 에이전트는 구성 파일 봇과 사용자가 생성한 에이전트를 하나의 풀로 함께 계산합니다. 워크스페이스에 해당 수준이 허용하는 것보다 많은 에이전트가 있으면, 플러그인은 구성 파일 봇을 먼저(구성 순서대로), 그다음 사용자가 생성한 에이전트를(오래된 순으로) 상한까지 활성화합니다. 나머지 에이전트는 저장된 채로 비활성 상태가 되며, 서버 로그에 이름이 기록되고 사유와 함께 Agents 페이지에 비활성으로 표시됩니다. 상한을 초과하여 에이전트를 생성하면 상한을 높여주는 수준의 이름이 포함된 라이선스 오류가 반환됩니다.
• 자체 LLM 사용 — Free 및 Professional 워크스페이스는 하나의 LLM 서비스, 즉 서비스 목록의 첫 번째 서비스를 사용합니다. 다른 서비스를 참조하는 에이전트는 해당 수준에서 비활성 상태이며 에이전트 상한의 슬롯을 차지하지 않습니다. 이러한 에이전트는 서버 로그에 이름이 기록되고 Agents 페이지에 비활성으로 표시됩니다. LLM Bridge 서비스 호출은 해당 서비스만 대상으로 합니다. Enterprise 이상에서는 에이전트와 LLM Bridge 호출이 구성된 모든 서비스로 라우팅됩니다. 폴백 체인은 Enterprise Advanced에서 따라가며, 그보다 낮은 수준에서는 구성된 폴백이 저장된 채로 남지만 요청은 기본 서비스만 사용합니다.
• 기본 제공 Mattermost 도구 — 읽기 전용 도구(메시지, 채널, 사용자, 팀, 파일, 검색 결과 조회)는 모든 수준에서 사용할 수 있습니다. Mattermost의 상태를 변경하는 도구(게시, 리액션, 편집, 채널·북마크·예약 게시물 등의 생성 또는 수정과 유사한 작업)는 Enterprise 이상에서 사용할 수 있으며, 그보다 낮은 수준에서는 도구 목록에 나타나지 않고 해당 도구에 대한 호출은 라이선스 메시지를 반환합니다.
• 도구 승인 정책 — 관리자가 구성하는 도구별 실행 정책은 Enterprise 이상에서 적용됩니다. 그보다 낮은 수준에서는 내장 Mattermost 도구가 제품 기본값을 사용하고 그 외의 모든 도구는 실행 전에 확인을 요청합니다. 관리자가 기본값보다 좁게 설정한 정책(예: 확인 요청)은 계속 적용됩니다. 관리자가 비활성화한 도구는 모든 수준에서 비활성화된 상태로 유지됩니다.
• 공유 프롬프트 라이브러리 — 개인 프롬프트는 모든 수준에서 사용할 수 있습니다. 프롬프트를 다른 사용자에게 게시하는 것, 그리고 다른 사용자가 게시한 프롬프트를 검색하고 사용하는 것은 Enterprise 이상에서 사용할 수 있습니다.

모든 수준에서 다음이 적용됩니다.

• 구성 읽기는 제한되지 않습니다. 관리자와 사용자는 항상 구성이 어떻게 설정되어 있는지 볼 수 있습니다.
• 끄는 작업은 제한되지 않습니다. 어떤 기능이든 구성을 비활성화, 지우기 또는 삭제하는 것은 항상 허용되므로, 라이선스 수준이 바뀐 후에도 워크스페이스가 상태를 정리할 수 있습니다.
• Mattermost Server v12.0 이상에서는 플러그인을 다시 시작하지 않아도 라이선스 변경이 적용됩니다. 이전 서버에서는 요청 시점 확인이 새 라이선스를 즉시 따르지만, 활성 에이전트 및 서비스 집합, 시맨틱 검색, MCP 연결은 다음 플러그인 구성 변경이나 재시작 시 다시 평가됩니다.
• 라이선스 사유로 거부된 요청은 실행 가능한 error 메시지와 license_required 필드(professional, enterprise 또는 enterprise_advanced)가 담긴 JSON 본문과 함께 HTTP 403을 반환합니다.

추가 구성 가이드#

• AWS Bedrock으로 Agents 구성