🤖 \_CHMCP服务器模板
Rancher Apps上的主机模型上下文协议（MCP）提示和工具，使像Claude这样的人工智能助手能够通过安全、经过身份验证的界面与您的copula工作区进行交互。
这是什么？
此模板允许您创建一个在copula Apps上运行的MCP服务器。你可以：
- 📝 添加提示 作为简单的markdown文件
prompts/文件夹 - 🛠️ 创建工具 作为Python函数，它利用了copula SDK
- 🔐 安全地进行身份验证 通过copula Apps使用OAuth
- 🚀 立即部署 使Claude可以访问您的MCP服务器
将其视为Claude和您的copula工作区之间的桥梁——您定义Claude可以看到和做什么，其余的由此服务器处理。
原理
架构概述
┌─────────────┐ MCP Protocol ┌──────────────────┐ OAuth ┌─────────────────┐
│ Claude │ ◄─────────────────────► │ dba-mcp-proxy │ ◄──────────────────► │ Databricks App │
│ CLI │ (stdio/JSON-RPC) │ (local process) │ (HTTPS/SSE) │ (MCP Server) │
└─────────────┘ └──────────────────┘ └─────────────────┘
▲ │
│ ▼
└────────── Databricks OAuth ──────► Workspace APIs组件
- MCP服务器 (
server/app.py)：带有集成MCP服务器的FastAPI应用程序：
- 从动态加载提示 prompts/*.md 文件 - 通过以下方式将Python函数作为MCP工具公开 @mcp_server.tool 装饰器 - 通过服务器发送事件处理HTTP请求和MCP协议
- 提示 (
prompts/)：简单的标记文件，其中：
- 文件名=提示名称（例如。， check_system.md → check_system 提示） - 第一行与 # =描述 - 文件内容=返回给Claude的内容
- 本地代理 (
dba_mcp_proxy/)：对MCP请求进行身份验证和代理：
- 自动处理Rancher OAuth身份验证 - Claude的stdio协议与HTTP/SSE之间的转换 - 适用于本地开发和部署的应用程序
🎬 演示
这段10分钟的视频向您展示了如何与Claude一起设置和使用AppDCP服务器：https://www.youtube.com/watch?v=oKE59zgb6e0
本视频演示了如何在Claude中使用自定义作业界面创建自己的MCP服务器。
快速开始
创建自己的MCP服务器
步骤1：使用此模板
或者使用GitHub CLI：
gh repo create my-mcp-server --template databricks-solutions/custom-mcp-databricks-app --private步骤2：克隆和设置
# Clone your new repository
git clone https://github.com/YOUR-USERNAME/my-mcp-server.git
cd my-mcp-server
# Run the interactive setup
./setup.sh这将：
- 配置copula身份验证
- 设置您的MCP服务器名称
- 安装所有依赖项
- 创建您的
.env.local文件
步骤3：与Claude一起部署
在Claude Code中，运行：
/setup-mcp这将：
- 将您的MCP服务器部署到copula Apps
- 配置MCP集成
- 显示可用的提示和工具
然后重新启动Claude Code以使用新的MCP服务器。
添加到Claude CLI
部署后，将您的MCP服务器添加到Claude：
# Set your Databricks configuration
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_APP_URL="https://your-app.databricksapps.com" # Get this from ./app_status.sh
export SERVER_NAME="your-server-name" # This comes from config.yaml (set during ./setup.sh)
# Add your MCP server to Claude (user-scoped)
claude mcp add $SERVER_NAME --scope user -- \
uvx --refresh --from git+ssh://git@github.com/YOUR-USERNAME/your-repo.git dba-mcp-proxy \
--databricks-host $DATABRICKS_HOST \
--databricks-app-url $DATABRICKS_APP_URL地方发展
# Clone and setup
git clone
cd
./setup.sh
# Start dev server
./watch.sh
# Set your configuration for local testing
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_APP_URL="http://localhost:8000" # Local dev server
# Add to Claude for local testing
claude mcp add databricks-mcp-local --scope local -- \
uvx --refresh --from git+ssh://git@github.com/YOUR-ORG/YOUR-REPO.git dba-mcp-proxy \
--databricks-host $DATABRICKS_HOST \
--databricks-app-url $DATABRICKS_APP_URL定制指南
此模板使用 FastMCP，一个易于构建MCP服务器的框架。FastMCP提供了两个主要的装饰器来扩展功能：
@mcp_server.prompt-用于注册返回文本的提示@mcp_server.tool-用于注册执行功能的工具
添加提示
最简单的方法是在 prompts/ 目录：
# Get cluster information
List all available clusters in the workspace with their current status提示将自动加载以下内容：
- 名字：不带扩展名的文件名（例如。，
get_clusters.md→get_clusters) - 描述：后面的第一行
# - 内容：整个文件内容
或者，您可以将提示注册为中的函数 server/app.py:
@mcp_server.prompt(name="dynamic_status", description="Get dynamic system status")
async def get_dynamic_status():
# This can include dynamic logic, API calls, etc.
w = get_workspace_client()
current_user = w.current_user.me()
return f"Current user: {current_user.display_name}\nWorkspace: {DATABRICKS_HOST}"我们自动装载 prompts/ 为了方便起见，但当您需要动态内容时，基于函数的提示很有用。
添加工具
在中添加功能 server/app.py 使用 @mcp_server.tool 装饰师：
@mcp_server.tool
def list_clusters(status: str = "RUNNING") -> dict:
"""List Databricks clusters by status."""
w = get_workspace_client()
clusters = []
for cluster in w.clusters.list():
if cluster.state.name == status:
clusters.append({
"id": cluster.cluster_id,
"name": cluster.cluster_name,
"state": cluster.state.name
})
return {"clusters": clusters}工具必须：
- 使用
@mcp_server.tool装饰器 - 有一个文档字符串（成为工具描述）
- 返回JSON可序列化数据（字典、列表、字符串等）
- 仅接受JSON可序列化参数
部署
# Deploy to Databricks Apps
./deploy.sh
# Check status and get your app URL
./app_status.sh您的MCP服务器将在 https://your-app.databricksapps.com/mcp/
这 app_status.sh 脚本将显示您部署的应用程序URL，您需要该URL DATABRICKS_APP_URL 将MCP服务器添加到Claude时的环境变量。
认证
- 地方发展：不需要身份验证
- 生产：OAuth由代理使用您的Rancher CLI凭据自动处理
例子
与克劳德一起使用
添加后，您可以在Claude中与MCP服务器交互：
Human: What prompts are available?
Claude: I can see the following prompts from your Databricks MCP server:
- check_system: Get system information
- list_files: List files in the current directory
- ping_google: Check network connectivity工具使用示例
Human: Can you execute a SQL query to show databases?
Claude: I'll execute that SQL query for you using the execute_dbsql tool.
[Executes SQL and returns results]项目结构
├── server/ # FastAPI backend with MCP server
│ ├── app.py # Main application + MCP tools
│ └── routers/ # API endpoints
├── prompts/ # MCP prompts (markdown files)
│ ├── check_system.md
│ ├── list_files.md
│ └── ping_google.md
├── dba_mcp_proxy/ # MCP proxy for Claude CLI
│ └── mcp_client.py # OAuth + proxy implementation
├── client/ # React frontend (optional)
├── scripts/ # Development tools
└── pyproject.toml # Python package configuration高级用法
环境变量
在中配置 .env.local:
DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
DATABRICKS_TOKEN=your-token # For local development
DATABRICKS_SQL_WAREHOUSE_ID=your-warehouse-id # For SQL tools创建复杂工具
工具可以访问完整的copula SDK：
@mcp_server.tool
def create_job(name: str, notebook_path: str, cluster_id: str) -> dict:
"""Create a Databricks job."""
w = get_workspace_client()
job = w.jobs.create(
name=name,
tasks=[{
"task_key": "main",
"notebook_task": {"notebook_path": notebook_path},
"existing_cluster_id": cluster_id
}]
)
return {"job_id": job.job_id, "run_now_url": f"{DATABRICKS_HOST}/#job/{job.job_id}"}测试您的MCP服务器
此模板包括用于在多个级别验证MCP功能的全面测试工具。
快速验证
将MCP服务器添加到Claude后，验证其是否正常工作：
# List available prompts and tools
echo "What MCP prompts are available from databricks-mcp?" | claude
# Test a specific prompt
echo "Use the check_system prompt from databricks-mcp" | claude综合测试套件
这 claude_scripts/ 目录包含6个用于彻底MCP验证的测试工具：
命令行测试
# Test local MCP server (requires ./watch.sh to be running)
./claude_scripts/test_local_mcp_curl.sh # Direct HTTP/curl tests with session handling
./claude_scripts/test_local_mcp_proxy.sh # MCP proxy client tests
# Test remote MCP server (requires Databricks auth and deployment)
./claude_scripts/test_remote_mcp_curl.sh # OAuth + HTTP tests with dynamic URL discovery
./claude_scripts/test_remote_mcp_proxy.sh # Full end-to-end MCP proxy tests交互式Web UI测试
# Launch MCP Inspector for visual testing (requires ./watch.sh for local)
./claude_scripts/inspect_local_mcp.sh # Local server web interface
./claude_scripts/inspect_remote_mcp.sh # Remote server web interfaceMCP检查器功能：
- 🖥️ 基于Web的交互式MCP服务器测试界面
- 🔧 使用参数输入表单执行可视化工具
- 📊 实时请求/响应监控
- 🐛 协议级调试和错误检查
- 📋 完整的工具和资源发现
每个测试验证什么
| 测试类型 | 身份验证 | 协议 | 会话管理 | 工具发现 |
|---|---|---|---|---|
| 卷曲试验 | ✅ | ✅ | ✅ | ✅ |
| 代理测试 | ✅ | ✅ | ✅ | ✅ |
| MCP检查员 | ✅ | ✅ | ✅ | ✅ |
所有测试都会动态发现应用程序URL并自动处理OAuth身份验证。
看 claude_scripts/README.md 详细文档。
故障排除
- 身份验证错误：运行
databricks auth login刷新凭据 - 未找到MCP：确保应用程序已部署且可访问
- 工具错误：查看日志
https://your-app.databricksapps.com/logz - MCP连接问题:
- 检查克劳德日志： tail -f ~/Library/Logs/Claude/*.log - 验证代理是否正常工作： uvx --refresh --from git+ssh://... dba-mcp-proxy --help - 使用回声管进行测试： echo "list your mcp commands" | claude
- 缓存版本问题：如果更新后出现缺少参数的错误：
# Clear uvx cache for this package
rm -rf ~/.cache/uv/git-v0/checkouts/*/
# Or clear entire uv cache
uv cache clean贡献
- 分叉存储库
- 添加您的提示和工具
- 本地测试
./watch.sh - 提交拉取请求
许可证
看 许可证.md