Databricks가 아닌 클라이언트를 Databricks MCP 서버에 연결

Important

이 기능은 베타 버전으로 제공됩니다. 작업 영역 관리자는 미리 보기 페이지에서 이 기능에 대한 액세스를 제어할 수 있습니다. Azure Databricks 미리 보기 관리를 참조하세요.

MCP(모델 컨텍스트 프로토콜)를 지원하는 비 Databricks(외부) 클라이언트, AI 도우미 및 IDE를 Databricks MCP 서버에 연결합니다. 이렇게 하면 개발 환경에서 직접 Databricks 데이터 및 도구에 액세스할 수 있습니다.

외부 클라이언트를 Databricks MCP 서버에 연결하면 다음을 수행할 수 있습니다.

IDE 또는 AI 도우미에서 Unity 카탈로그 함수, 테이블 및 벡터 인덱스에 액세스
Claude, Cursor, Replit 또는 기타 MCP 지원 도구를 통해 Databricks 데이터를 직접 쿼리하다

Prerequisites

서버 URL: 사용하려는 Databricks MCP 서버에 대한 적절한 서버 URL을 가져옵니다.
리소스 액세스: 사용하려는 MCP 서버 및 기본 리소스에 대한 액세스 권한이 있는지 확인합니다. 예를 들어 Genie 관리형 MCP 서버를 사용하는 경우 기본 Genie 공간에 액세스해야 합니다.
네트워크 액세스: Databricks 작업 영역에 IP 액세스 제한이 있는 경우 클라이언트의 아웃바운드 IP 주소를 허용 목록에 추가하여 작업 영역에 연결할 수 있도록 합니다.
- 작업 영역 IP 액세스 목록 및 계정 IP 액세스 목록에 대한 설명서에 따라 제한 사항이 있는지 확인합니다.
- IP 액세스 목록을 사용하는 경우 클라이언트의 아웃바운드 IP를 식별합니다. 이 정보는 일반적으로 클라이언트 설명서에서 사용할 수 있습니다. 예를 들어 Claude는 아웃바운드 IP 주소를 여기에 문서화합니다.
- 클라이언트의 아웃바운드 IP가 목록에 추가되었는지 확인합니다.

인증 방법

보안 요구 사항에 가장 적합한 인증 방법을 선택합니다.

메서드	관리/외부 MCP	사용자 지정 MCP	보안 수준	적합한 대상
OAuth(권장)	지원됨	지원됨	높음 - 범위가 지정된 권한, 자동 토큰 갱신	프로덕션 사용, 팀 환경, 장기 액세스
개인용 액세스 토큰	지원됨	지원되지 않음	중간 옵션 - 만료가 설정된 토큰 기반 액세스	개별 개발, 테스트, 단기 액세스

OAuth 인증을 사용하여 클라이언트 연결

OAuth는 범위가 지정된 권한 및 자동 토큰 새로 고침을 사용하여 보안 인증을 제공합니다.

비고

Databricks MCP 서버는 MCP 권한 부여 사양에 따라 두 클라이언트 유형을 모두 지원합니다.

공용 클라이언트: 클라이언트 암호가 필요하지 않음
기밀 클라이언트: 클라이언트 암호 포함

클라이언트의 OAuth 리디렉션 URL 가져오기

각 MCP 클라이언트에는 인증 콜백을 위한 특정 OAuth 리디렉션 URL이 필요합니다. 일반적인 리디렉션 URL 패턴은 다음과 같습니다.

웹 기반 클라이언트: https://<domain>/oauth/callback 또는 https://<domain>/api/mcp/auth_callback
로컬 개발 도구: http://localhost:<port>/oauth/callback

클라이언트의 설명서를 확인하여 필요한 정확한 리디렉션 URL을 찾습니다.

Databricks OAuth 애플리케이션 만들기

계정 관리자가 Databricks OAuth 애플리케이션을 만들게 합니다. 클라이언트 ID를 검색하고 클라이언트에 필요한 경우 클라이언트 암호를 검색합니다.

UI 기반(계정 콘솔)

계정 콘솔을 사용하여 Databricks OAuth 애플리케이션을 만듭니다.

Databricks 계정 콘솔에서 설정>앱 연결>연결 추가 연결로 이동합니다.
애플리케이션 설정을 구성합니다.
- 이름: OAuth 애플리케이션에 대한 설명이 포함된 이름을 입력합니다(예: claude-mcp-clientmcp-inspector
- 리디렉션 URL: 외부 클라이언트에 필요한 리디렉션 URL 추가
- 클라이언트 유형: 공용 클라이언트(브라우저 기반, 모바일)의 경우 클라이언트 암호 생성을 선택 취소합니다. 기밀 클라이언트(서버 쪽)의 경우 계속 확인합니다.
- 범위: API 범위 구성(아래 OAuth 범위 구성 참조)
- 토큰 만료: 적절한 토큰 액세스 및 새로 고침 시간 설정

CLI

Databricks CLI를 사용하여 Databricks OAuth 애플리케이션을 만듭니다.

databricks account custom-app-integration create --json '{
  "name": "mcp-oauth-client",
  "redirect_urls": ["https://<your-client-redirect-url>"],
  "confidential": false,
  "scopes": ["all-apis"],
  "token_access_policy": {
    "access_token_ttl_in_minutes": 60,
    "refresh_token_ttl_in_minutes": 10080
  }
}'

클라이언트의 실제 리디렉션 URL로 대체 <your-client-redirect-url> 합니다.

OAuth 범위 구성

OAuth 범위는 클라이언트가 액세스할 수 있는 Databricks API를 제어합니다. 대부분의 사용 사례에서 모든 Databricks API에 대한 액세스 권한을 부여하고 가장 간단한 옵션인 범위를 사용합니다 all-apis .

보다 세부적인 제어를 위해 all-apis 대신 MCP 관련 범위를 지정할 수 있습니다.

MCP 서버 유형	필수 범위
MCP 지니 공간	`mcp.genie`
MCP Unity 카탈로그 함수	`mcp.functions`
MCP 벡터 검색	`mcp.vectorsearch`
MCP Databricks SQL	`mcp.sql`, `sql.warehousessql.statement-execution`
MCP 외부 함수	`mcp.external`

REST API 범위를 선언하고 에이전트와 함께 사용하는 방법에 대한 자세한 내용은 에이전트를 로깅할 때 REST API 범위 선언을 참조하세요.

네트워크 액세스 구성(선택 사항)

Databricks 작업 영역에 IP 액세스 제한이 있는 경우 클라이언트의 아웃바운드 IP 주소를 작업 영역 허용 목록에 추가합니다. 그렇지 않으면 작업 영역에서 클라이언트의 인증 요청을 차단합니다. IP 액세스 목록 관리를 참조하세요.

클라이언트 구성

Databricks에서 OAuth 애플리케이션을 만든 후 OAuth 자격 증명을 사용하여 특정 MCP 클라이언트를 구성합니다. 각 클라이언트에는 고유한 구성 방법이 있습니다. 인기 있는 MCP 클라이언트에 대한 자세한 지침은 다음 플랫폼별 예제를 참조하세요.

OAuth 예제

다음 예제에서는 OAuth 인증을 사용하여 특정 MCP 클라이언트를 구성하는 방법을 보여 줍니다. 먼저 이전 섹션의 일반 OAuth 설정 단계를 수행한 다음, 이러한 예제를 사용하여 특정 클라이언트를 구성합니다.

MCP 검사기

MCP 검사기는 MCP 서버를 테스트하고 디버깅하기 위한 개발자 도구입니다.

MCP 검사기

다음 검사기별 설정을 사용하여 위의 OAuth 인증 설정을 따릅니다.

리디렉션 URL:
- http://localhost:6274/oauth/callback
- http://localhost:6274/oauth/callback/debug
클라이언트 유형: 공용( 클라이언트 암호 생성 선택 취소)

MCP 검사기 구성:

검사기를 실행합니다: npx @modelcontextprotocol/inspector.
전송 유형을Streamable HTTP로 설정합니다.
Databricks MCP 서버 URL을 입력합니다.
인증 섹션에서 OAuth 클라이언트 ID를 추가합니다.
인증 설정 열기를 클릭하고 안내 또는 빠른 흐름을 선택합니다.
인증에 성공하면 API 토큰 인증 섹션 아래에 전달자 토큰에 액세스 토큰을 붙여넣습니다.
연결을 클릭합니다.

MCP 검사기 인증 흐름

클로드 커넥터

원격 MCP와 함께 Claude Connectors를 사용하여 Databricks 관리 및 외부 MCP 서버에 Claude를 연결합니다.

다음 Claude 관련 설정을 사용하여 위의 OAuth 인증 설정을 따릅니다.

리디렉션 URL: https://claude.ai/api/mcp/auth_callback 및 https://claude.com/api/mcp/auth_callback
IP 허용 목록(필요한 경우): Claude의 아웃바운드 IP 주소 추가

Claude 설정:

Claude의 설정 >커넥터 로 이동합니다.
사용자 지정 커넥터 추가를 클릭합니다.
Databricks MCP 서버 URL을 입력합니다.
OAuth 애플리케이션의 클라이언트 ID를 입력합니다.
추가를 클릭하여 마칩니다.

Claude에서 커넥터 구성

커서/윈드서프

커서 또는 Windsurf와 같은 로컬 IDE를 Databricks MCP 서버에 안전하게 연결하려면 OAuth와 함께 사용합니다 mcp-remote . mcp-remote 리포지토리 지침에 따라 mcp-remote을 설정합니다. 그런 다음 OAuth 인증 설정 에 따라 OAuth가 올바르게 설정되었는지 확인합니다.

커서 또는 Windsurf 설정:

MCP 구성 파일을 찾습니다.
- 커서: ~/.cursor/mcp.json
- 윈드서프: ~/.codeium/windsurf/mcp_config.json

구성 파일에서 MCP 서버를 추가합니다.

기밀 OAuth 클라이언트의 경우 (클라이언트 암호 사용):

{
  "mcpServers": {
    "databricks-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-workspace-hostname>/api/2.0/mcp/functions/system/ai",
        "--static-oauth-client-info",
        "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\", \"client_secret\": \"$MCP_REMOTE_CLIENT_SECRET\" }"
      ]
    }
  }
}

공용 OAuth 클라이언트의 경우(클라이언트 암호 제외):

{
  "mcpServers": {
    "databricks-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-workspace-hostname>/api/2.0/mcp/functions/system/ai",
        "--static-oauth-client-info",
        "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\" }"
      ]
    }
  }
}

<your-workspace-hostname> Databricks 작업 영역 호스트 이름으로 대체합니다.
OAuth 클라이언트 ID를 사용하여 환경 변수 MCP_REMOTE_CLIENT_ID 를 설정합니다. 비공개 클라이언트의 경우 클라이언트 시크릿을 사용하여 MCP_REMOTE_CLIENT_SECRET를 설정하세요.

PAT(개인 액세스 토큰) 인증을 사용하여 클라이언트 연결

개인 액세스 토큰은 Databricks MCP 서버에 대한 개별 개발, 테스트 및 단기 액세스에 적합한 더 간단한 인증 방법을 제공합니다.

비고

개인 액세스 토큰은 관리형 및 외부 MCP 서버에 대해서만 지원됩니다. 사용자 지정 MCP 서버에는 OAuth 인증이 필요합니다.

Databricks 작업 영역에서 개인용 액세스 토큰을 생성합니다. Azure Databricks 개인용 액세스 토큰(레거시)을 사용하여 인증을 참조하세요.
네트워크 액세스를 구성합니다(선택 사항).

Databricks 작업 영역에 IP 액세스 제한이 있는 경우 클라이언트의 아웃바운드 IP 주소를 허용 목록에 추가합니다. 필요한 IP 주소를 얻으려면 클라이언트의 설명서 또는 배포 환경의 네트워크 구성을 참조하세요.
클라이언트를 구성합니다.

PAT를 생성한 후 인증에 사용하도록 MCP 클라이언트를 구성합니다. 각 클라이언트에는 고유한 구성 방법이 있습니다. 인기 있는 MCP 클라이언트에 대한 자세한 지침은 아래 플랫폼별 예제를 참조하세요.

PAT 예제

다음 예제에서는 개인용 액세스 토큰 인증을 사용하여 특정 MCP 클라이언트를 구성하는 방법을 보여 줍니다. 먼저 위의 PAT 인증 설정에 따라 다음 예제를 사용하여 특정 클라이언트를 구성합니다.

Cursor

커서는 설정 구성을 통해 MCP를 지원합니다.

커서 설정을 엽니다.

다음 구성을 추가합니다( 선택한 MCP 서버에 대한 URL 조정).

{
  "mcpServers": {
    "uc-function-mcp": {
      "type": "streamable-http",
      "url": "https://<your-workspace-hostname>/api/2.0/mcp/functions/{catalog_name}/{schema_name}",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      },
      "note": "Databricks UC function"
    }
  }
}

<your-workspace-hostname> Databricks 작업 영역 호스트 이름으로 대체합니다.
<YOUR_TOKEN>을 개인용 액세스 토큰으로 대체합니다.

Claude Desktop

Claude Desktop 은 mcp-remote를 사용하여 Databricks MCP 서버에 연결할 수 있습니다.

파일을 찾아보세요.claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

다음 구성을 추가합니다( 선택한 MCP 서버에 대한 URL 조정).

{
  "mcpServers": {
    "uc-function-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-workspace-hostname>/api/2.0/mcp/functions/{catalog_name}/{schema_name}",
        "--header",
        "Authorization: Bearer <YOUR_TOKEN>"
      ]
    }
  }
}

<your-workspace-hostname> Databricks 작업 영역 호스트 이름으로 대체합니다.
<YOUR_TOKEN>을 개인용 액세스 토큰으로 대체합니다.
변경 내용을 적용하려면 Claude Desktop을 다시 시작합니다.

회신(Replit)

Replit 는 사용자 지정 MCP 서버 구성을 통해 Databricks MCP 서버에 연결할 수 있도록 지원합니다.

Replit 작업 영역에서 MCP 서버 추가를 클릭합니다.
Databricks MCP 서버 URL을 입력합니다. 예를 들면 다음과 같습니다.
```
https://<your-workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}
```
사용자 지정 헤더를 추가합니다.
- 키: Authorization
- 값: Bearer <YOUR_TOKEN>

Replit MCP 설명서를 참조하세요.

연결 문제 해결

다음 문제 해결 단계에 따라 일반적인 연결 문제를 진단하고 해결합니다.

인증 유효성 검사

연결을 테스트하기 전에 인증 자격 증명이 올바르게 구성되었는지 확인합니다.

서비스 프린시플(M2M)

M2M(컴퓨터 대 컴퓨터) OAuth를 사용한 서비스 주체 인증의 경우 Databricks CLI를 사용하여 자격 증명을 테스트합니다.

DATABRICKS_CLIENT_ID=<your-client-id> DATABRICKS_CLIENT_SECRET=<your-client-secret> databricks auth describe

이 명령은 서비스 주체 구성의 유효성을 검사하고 인증된 ID에 대한 정보를 표시합니다. 명령이 오류를 반환하는 경우 서비스 주체 설정을 검토하고 다음을 확인합니다.

Databricks 계정에 서비스 주체가 생성되었습니다.
클라이언트 ID 및 클라이언트 암호가 올바르게 구성됨
서비스 주체에 필요한 리소스에 액세스할 수 있는 적절한 권한이 있습니다.

OAuth U2M(사용자-컴퓨터)

OAuth U2M(사용자-컴퓨터) 인증의 경우 MCP 검사 기로 연결을 테스트 합니다. OAuth 흐름은 연결 프로세스 중에 자격 증명의 유효성을 검사합니다.

네트워크 구성 확인

네트워크 제한으로 인해 외부 클라이언트가 Databricks 작업 영역에 연결하지 못할 수 있습니다. 클라이언트가 Databricks 계정 및 작업 영역에 연결할 수 있도록 Databricks IP 액세스 목록 정책이 구성되어 있는지 확인합니다. 필수 조건을 참조하세요.

Databricks 지원에 문제 보고

다음 문제 해결 단계를 완료한 후 연결 문제가 계속 발생하는 경우:

MCP 클라이언트(Claude, Cursor, MCP Inspector 등)의 로그에서 오류 메시지 및 스택 추적을 검토합니다.
다음 진단 정보를 수집합니다.
- 사용되는 인증 방법(OAuth 또는 PAT)
- MCP 서버 URL
- 클라이언트의 오류 메시지
- 네트워크 구성 세부 정보(IP 제한, 방화벽 규칙)
지원 팀에 문의하고 진단 정보를 공유하여 문제를 해결합니다.

제한점

동적 클라이언트 등록: Databricks는 관리형, 외부 또는 사용자 지정 MCP 서버에 대한 동적 클라이언트 등록 OAuth 흐름을 지원하지 않습니다. OAuth 인증을 사용하여 동적 클라이언트 등록을 요구하는 외부 클라이언트 및 IDE는 지원되지 않습니다.
사용자 지정 MCP 서버 개인용 액세스 토큰 지원: Databricks Apps에서 호스트되는 사용자 지정 MCP 서버는 인증을 위한 개인용 액세스 토큰을 지원하지 않습니다.
대신 권한 부여: Databricks Apps에서 호스트되는 사용자 지정 MCP 서버는 사용자를 대신하는 권한 부여를 지원하지 않습니다.

다음 단계

관리형 MCP 서버를 사용하여 에이전트를 Unity 카탈로그 데이터에 연결
외부 MCP 서버를 사용하여 타사 서비스에 액세스
조직별 도구에 대한 사용자 지정 MCP 서버 호스트

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-01-10

다음을 통해 공유

Databricks가 아닌 클라이언트를 Databricks MCP 서버에 연결

Prerequisites

인증 방법

OAuth 인증을 사용하여 클라이언트 연결

클라이언트의 OAuth 리디렉션 URL 가져오기

Databricks OAuth 애플리케이션 만들기

UI 기반(계정 콘솔)

CLI

OAuth 범위 구성

네트워크 액세스 구성(선택 사항)

클라이언트 구성

OAuth 예제

MCP 검사기

클로드 커넥터

커서/윈드서프

PAT(개인 액세스 토큰) 인증을 사용하여 클라이언트 연결

PAT 예제

Cursor

Claude Desktop

회신(Replit)

연결 문제 해결

인증 유효성 검사

서비스 프린시플(M2M)

OAuth U2M(사용자-컴퓨터)

네트워크 구성 확인

Databricks 지원에 문제 보고

제한점

다음 단계

피드백

추가 리소스