Knowi MCP 서버

Claude Code, Claude Desktop, Cursor 또는 기타 MCP 호환 AI 클라이언트를 Knowi에 연결하세요. AI 어시스턴트에서 직접 자연어로 데이터를 쿼리하고, 대시보드를 생성하고, 보고서를 관리하는 등의 작업을 수행할 수 있습니다.

MCP 서버는 Knowi 애플리케이션에 내장되어 있습니다. 별도의 설치가 필요하지 않습니다.

빠른 시작

1. MCP 토큰 생성

1. Knowi에 로그인합니다.

2. **설정(Settings) → AI 설정(AI Settings)**으로 이동합니다.

3. MCP 토큰(MCP Token) 아래에서 만료 기간을 선택하고 **토큰 생성(Generate Token)**을 클릭합니다.

4. 토큰을 복사하세요. 토큰은 한 번만 표시됩니다.

2. Claude Code에 연결

claude mcp add knowi https://your-instance.knowi.com/api/2.0/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_MCP_TOKEN"

knowi.com 계정의 경우:

claude mcp add knowi https://www.knowi.com/api/2.0/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_MCP_TOKEN"

3. Claude Desktop에 연결

구성 파일을 편집하세요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "knowi": {
      "type": "streamable-http",
      "url": "https://your-instance.knowi.com/api/2.0/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

저장 후 Claude Desktop을 다시 시작하세요.

4. 확인

"What Knowi tools are available?"

knowi_do, knowi_ask, knowi_search, knowi_list_dashboards 등을 포함한 도구가 표시되어야 합니다.

Related MCP server: AgenticBI

사용 가능한 도구

AI 기반 도구

Knowi의 AI 오케스트레이터를 사용하여 지침을 해석하고 작업을 연결하는 자연어 도구입니다.

결정론적 도구

예측 가능한 동작을 수행하는 직접적이고 빠른 작업입니다.

사용 예시

"Show me my Knowi dashboards"

"Ask Knowi: what were our top customers by revenue last month?"

"Create a sales dashboard with revenue trends and top products"

"Search Knowi for dashboards related to customer analytics"

"Get the data from the Monthly Revenue widget"

"Export the Executive Summary dashboard to PDF"

"Push these sales records to a Knowi dataset called 'Daily Sales'"

"Set up a daily email report for the executive dashboard"

토큰 관리

토큰 교체:

1. **설정(Settings) → AI 설정(AI Settings) → MCP 토큰(MCP Token)**으로 이동합니다.

2. **토큰 취소(Revoke Token)**를 클릭합니다.

3. 새 토큰을 생성하고 구성을 업데이트하세요:

claude mcp remove knowi
claude mcp add knowi https://your-instance.knowi.com/api/2.0/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_NEW_TOKEN"

사용자당 하나의 토큰. 새 토큰을 생성하면 이전 토큰은 자동으로 취소됩니다.

API 참조

MCP 서버는 Streamable HTTP(MCP 클라이언트용)와 REST 엔드포인트(직접 프로그래밍 방식 사용용)를 모두 노출합니다.

상태 확인

curl https://your-instance.knowi.com/api/2.0/mcp/health

{
  "status": "healthy",
  "toolCount": 28,
  "tools": ["knowi_do", "knowi_ask", "knowi_search", "..."],
  "activeSessions": 0
}

도구 나열

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-instance.knowi.com/api/2.0/mcp/tools

도구 호출 (REST)

curl -X POST https://your-instance.knowi.com/api/2.0/mcp/tools/call \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "knowi_list_dashboards",
    "arguments": {}
  }'

Streamable HTTP (JSON-RPC)

모든 MCP 클라이언트 작업은 표준 JSON-RPC와 함께 POST /api/2.0/mcp를 사용합니다:

# Initialize
curl -X POST https://your-instance.knowi.com/api/2.0/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

응답에는 후속 요청에 사용할 Mcp-Session-Id 헤더가 포함됩니다.

보안

• 범위가 지정된 자격 증명: MCP 토큰은 MCP 엔드포인트에만 액세스하며, 더 넓은 관리 API에 대해서는 사용할 수 없습니다.

• 모든 요청에 대한 권한 부여: 모든 도구는 실행 전에 인증된 사용자가 요청된 리소스에 대한 액세스 권한을 가지고 있는지 확인합니다.

• 프롬프트 주입 방지: AI 기반 도구는 지침에서 알려진 주입 패턴을 검색하고 AI 모델에 도달하기 전에 거부합니다.

• 파괴적 작업 보호: knowi_do는 삭제/드롭/퍼지 지침을 차단합니다. 삭제하려면 confirm: true 매개변수가 필요한 knowi_delete 도구를 명시적으로 사용해야 합니다.

• 데이터 잘림: knowi_get_data 및 knowi_ask는 기본적으로 최대 100개의 행을 반환합니다.

• 세션 보안: Streamable HTTP 세션은 인증된 사용자에 바인딩됩니다. 세션 ID만으로는 액세스 권한이 부여되지 않습니다.

데이터 흐름

Claude가 Knowi MCP 도구를 호출하면 도구 응답(데이터 행, 메타데이터, 인사이트)이 Claude로 반환되어 Anthropic의 인프라에서 처리됩니다. 이는 MCP의 본질적인 특성으로, 클라이언트가 작업을 수행하려면 결과를 받아야 합니다.

최대 데이터 격리를 위해서는 MCP 대신 Knowi의 제품 내 AI 에이전트를 사용하세요.

문제 해결

Claude에 도구가 나타나지 않는 경우:

• Claude Code / Claude Desktop을 완전히 다시 시작하세요.

• 서버에 연결할 수 있는지 확인하세요: curl https://your-instance.knowi.com/api/2.0/mcp/health

• 토큰이 유효한지 확인하세요: curl -H "Authorization: Bearer TOKEN" https://your-instance.knowi.com/api/2.0/mcp/tools

claude mcp list에서 "연결 실패(Failed to connect)":

• --transport http를 사용했는지 확인하세요 (Streamable HTTP에 필요).

• 전송 설정이 잘못된 경우 서버를 제거했다가 다시 추가하세요.

401 오류:

• 토큰이 만료되었거나 취소되었을 수 있습니다. 설정 → AI 설정에서 새 토큰을 생성하고 구성을 업데이트하세요.

도구 호출 시 액세스 거부 반환:

• 구성한 토큰의 사용자가 요청된 리소스에 대한 권한이 없습니다.

• 프로덕션 환경에서 사용하려면 최소한의 필수 권한을 가진 전용 Knowi 사용자를 생성하세요.

요구 사항

• AI 에이전트가 활성화된 Knowi 계정 (설정 → AI 설정)

• Claude Code CLI, Claude Desktop 또는 MCP 호환 클라이언트

문서

• MCP 서버 참조 — 전체 API 참조, 모든 도구 스키마, 보안 모델

• Claude Code 설정 가이드 — 단계별 설정 지침

• Knowi 문서 — 전체 제품 문서

지원

• 문서: knowi.com/docs

• 지원: support.knowi.com

• 이 저장소 관련 문제: GitHub 이슈 열기