{"id":39698338,"url":"https://github.com/databricks-solutions/mcp-workshop","last_synced_at":"2026-01-18T10:19:28.668Z","repository":{"id":319881740,"uuid":"1068007315","full_name":"databricks-solutions/mcp-workshop","owner":"databricks-solutions","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-20T17:33:50.000Z","size":602,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-20T18:32:42.064Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/databricks-solutions.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS.txt","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE.md","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T18:00:56.000Z","updated_at":"2025-10-20T15:28:14.000Z","dependencies_parsed_at":"2025-10-20T18:32:44.860Z","dependency_job_id":null,"html_url":"https://github.com/databricks-solutions/mcp-workshop","commit_stats":null,"previous_names":["databricks-solutions/mcp-workshop"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/databricks-solutions/mcp-workshop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Fmcp-workshop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Fmcp-workshop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Fmcp-workshop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Fmcp-workshop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/databricks-solutions","download_url":"https://codeload.github.com/databricks-solutions/mcp-workshop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/databricks-solutions%2Fmcp-workshop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28534320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T10:13:46.436Z","status":"ssl_error","status_checked_at":"2026-01-18T10:13:11.045Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-18T10:19:28.546Z","updated_at":"2026-01-18T10:19:28.651Z","avatar_url":"https://github.com/databricks-solutions.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Databricks MCP Workshop\n\nInteractive workshop for learning how to build agents on Databricks with hands-on examples covering managed servers, external integrations, custom server development and local IDE setup.\n\n## 🎓 Workshop Participant Setup\n\n**For workshop participants** - Get your own isolated environment with one command:\n\n```bash\ngit clone https://github.com/databricks-solutions/mcp-workshop\ncd mcp-workshop\n./setup.sh\n```\n\nThis interactive setup creates your personal workshop environment:\n- 🏗️ **Your own Unity Catalog** with sample data\n- 🚀 **Custom MCP server** deployed as a Databricks App\n- 💻 **Local development** environment\n- 🔐 **Secure authentication** setup\n\nEach participant gets isolated resources (e.g., `mcp_workshop_john_doe`) - no conflicts, no shared data issues!\n\n👉 **[See detailed setup guide →](./WORKSHOP_SETUP.md)**\n\n### 🏢 Enterprise/Admin-Managed Setup\n\nFor workshops where participants don't have catalog creation permissions:\n\n1. **Admin:** Run `setup/admin_bulk_setup.py` notebook → [Admin Guide](./ADMIN_WORKSHOP_GUIDE.md)\n2. **Participants:** Follow the quick start → [Participant Guide](./PARTICIPANT_QUICK_START.md)\n\nEach participant gets their own isolated schema within a shared catalog - no jobs, no catalog creation needed!\n\n---\n### Access the Workshop\n\nAfter deployment, access the workshop locally:\n\n1. Navigate to the frontend: `cd frontend`\n2. Start the dev server: `npm run dev`\n3. Visit **http://localhost:3000** to start the workshop\n\nYour MCP server will be deployed as a Databricks App (check the Apps page)\n\n## 📚 Workshop Content\n\n### Section 1: Managed MCP Servers (45 min)\nLearn to use Databricks-managed MCP servers with:\n- Unity Catalog functions and permissions\n- Vector Search for RAG applications  \n- Genie Spaces for natural language SQL\n- Automated vs Interactive modes\n\n### Section 2: External MCP Servers (40 min)\nIntegrate third-party services:\n- Unity Catalog connections\n- GitHub, Atlassian, Slack integrations\n- Custom API connections\n- Proxy authentication and security\n\n### Section 3: Custom MCP Servers (60 min)\nBuild and deploy your own:\n- Simple `@mcp.tool()` decorator pattern (based on [databrickslabs/mcp](https://github.com/databrickslabs/mcp))\n- Databricks SDK integration (clusters, warehouses, SQL)\n- Markdown-based prompts for reusable commands\n- **Databricks Apps deployment** with automated scripts\n- End-to-end testing and debugging tools\n\n### Section 4: Local IDE Integration (30 min)\nConnect your development environment:\n- Cursor IDE configuration\n- Claude Desktop setup\n- VS Code with MCP extensions\n- OAuth and PAT authentication\n\n## 🔐 Authentication Model\n\nThis workshop uses **Databricks Apps built-in authentication** exclusively:\n\n- **User Authorization**: Your access token is automatically forwarded via `x-forwarded-access-token` header\n- **App Authorization**: Service principal credentials via `DATABRICKS_CLIENT_ID` and `DATABRICKS_CLIENT_SECRET` environment variables\n- **Unified Permissions**: All operations respect your existing Unity Catalog permissions\n- **Zero Setup**: No manual token management or OAuth flows required\n\n[Learn more about Databricks Apps authentication →](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/auth)\n\n## 🛠️ Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                 Databricks Workspace                        │\n├─────────────────────────────────────────────────────────────┤\n│  ┌─────────────────┐    ┌──────────────────────────────────┐ │\n│  │  Local Dev      │    │         Unity Catalog           │ │\n│  │  Frontend       │◄──►│  - mcp_workshop catalog         │ │\n│  │  (Next.js)      │    │  - Sample data \u0026 schemas        │ │\n│  │                 │    │  - Vector Search indexes       │ │\n│  │  http://        │    │  - Genie Spaces                │ │\n│  │  localhost:3000 │    └──────────────────────────────────┘ │\n│  └─────────────────┘                                        │\n│                         ┌──────────────────────────────────┐ │\n│  ┌─────────────────┐    │       MCP Integrations          │ │\n│  │  Setup Jobs     │    │  - Managed MCP servers          │ │\n│  │  - Catalog      │    │  - External connections         │ │\n│  │  - Sample data  │    │  - Custom MCP App (deployed)    │ │\n│  │  - Vector index │    └──────────────────────────────────┘ │\n│  └─────────────────┘                                        │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## 📁 Project Structure\n\n```\nmcp-workshop/\n├── databricks.yml              # Bundle configuration\n├── frontend/                   # Next.js workshop application (local dev)\n│   ├── src/\n│   │   ├── app/               # App router pages\n│   │   └── components/        # React components\n│   └── package.json\n├── custom-mcp-template/        # Custom MCP server (deployed to Databricks Apps)\n│   ├── server/                # FastAPI MCP server\n│   ├── client/                # React client UI\n│   └── deploy.sh              # Deployment script\n└── setup/                      # Workshop setup jobs\n    ├── create_workshop_catalog.py\n    ├── setup_sample_data.py\n    └── deploy_mcp_template.py\n```\n\n## 🎯 Learning Objectives\n\nBy the end of this workshop, you'll be able to:\n\n- ✅ Use Databricks managed MCP servers in your applications\n- ✅ Integrate external MCP servers via Unity Catalog connections\n- ✅ Build and deploy custom MCP servers as Databricks Apps\n- ✅ Implement proper authentication and authorization patterns\n- ✅ Apply MCP best practices for production deployments\n- ✅ Connect local IDEs to Databricks MCP resources  \n\n## 🔧 Development\n\nTo run the workshop locally for development:\n\n```bash\ncd app\nnpm install\nnpm run dev\n```\n\nThe app will run at `http://localhost:3000` with mock authentication for development.\n\n## 📝 Customization\n\n### Adding New Workshop Sections\n\n1. Update `src/lib/workshop-config.ts` with new section definitions\n2. Create component files in `src/components/workshop/sections/`\n3. Add any required setup jobs to `databricks.yml`\n4. Deploy with `databricks bundle deploy`\n\n### Modifying Authentication Scopes\n\nUpdate the `user_authorization.scopes` in `databricks.yml`:\n\n```yaml\nuser_authorization:\n  enabled: true\n  scopes:\n    - \"sql\"                    # SQL warehouse access\n    - \"files.files\"           # File operations  \n    - \"dashboards.genie\"      # Genie Spaces (add if needed)\n    - \"your-custom-scope\"     # Additional scopes\n```\n\n## 🧹 Workshop Management\n\n### Cleanup After Workshop (for workspace admins/instructors)\n\nThe workshop creates user-specific resources in the workspace that should be cleaned up afterwards:\n\n```bash\n# List all workshop participants\n./cleanup_workshop.sh --list\n\n# Clean up specific participant\n./cleanup_workshop.sh --participant john_doe\n\n# Clean up ALL workshop resources (⚠️ DESTRUCTIVE)\n./cleanup_workshop.sh --all\n```\n\n### Monitor Workshop Usage\n\n```bash\n# View participant resources\n./cleanup_workshop.sh --list\n\n# Check catalog sizes\ndatabricks sql query \"SELECT catalog_name, SIZE_GB FROM information_schema.catalog_storage WHERE catalog_name LIKE 'mcp_workshop_%'\"\n\n# List workshop apps\ndatabricks apps list | grep \"mcp-custom-server-\"\n```\n\n\n## 🆘 Troubleshooting\n\n### Common Issues\n\n**App won't start**: Check that all required environment variables are set in the bundle configuration.\n\n**Authentication errors**: Ensure user authorization is enabled and required scopes are configured.\n\n**Resource access denied**: Verify Unity Catalog permissions for the workshop catalog and resources.\n\n**Health check failing**: Check that the app is listening on port 3000 and `/api/health` endpoint responds.\n\n**Setup script fails**: Ensure Databricks CLI is configured and you have catalog creation permissions.\n\n### Getting Help\n\n- Check the app logs in Databricks workspace\n- Verify bundle deployment with `databricks bundle validate`\n- Review [Databricks Apps documentation](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/)\n- For participant setup issues, see [WORKSHOP_SETUP.md](./WORKSHOP_SETUP.md)\n- Submit issues to the workshop repository\n\n## 🔀 Choosing Your MCP Approach\n\nThis workshop uses a simplified approach based on **[databrickslabs/mcp](https://github.com/databrickslabs/mcp)** - perfect for learning MCP fundamentals.\n\n### This Workshop: databrickslabs/mcp\n✅ **Simpler structure** - fewer files, easier to understand  \n✅ **Focus on tool creation** - `@mcp.tool()` decorator pattern  \n✅ **Officially supported** - maintained by Databricks Labs  \n✅ **Quick deployment** - streamlined for Databricks Apps  \n\n### Alternative: databricks-solutions Repository\n\nFor **Claude Code/Cursor users** wanting enhanced IDE integration:\n\n**[databricks-solutions/custom-mcp-databricks-app](https://github.com/databricks-solutions/custom-mcp-databricks-app)**\n\nFeatures:\n- Enhanced IDE integration (Claude Code, Cursor)\n- `.claude/commands` directory support\n- FastMCP framework with routers\n- Built-in MCP inspector\n- More production-ready patterns\n\n**💡 Recommendation:** Start with this workshop to learn the fundamentals. If you're a heavy Claude Code or Cursor user, explore the databricks-solutions repository as your next step!\n\n## 📖 Additional Resources\n\n- [databrickslabs/mcp Repository](https://github.com/databrickslabs/mcp) - Official examples\n- [Databricks MCP Documentation](https://docs.databricks.com/mcp)\n- [Model Context Protocol Specification](https://modelcontextprotocol.io)\n- [Databricks Apps Guide](https://docs.databricks.com/dev-tools/databricks-apps)\n- [FastMCP Documentation](https://fastmcp.org/)\n\n## 📄 License\n\n\u0026copy; 2025 Databricks, Inc. All rights reserved. The source in this notebook is provided subject to the Databricks License [https://databricks.com/db-license-source]. All included or referenced third party libraries are subject to the licenses set forth below.\n\n---\n\n**Ready to learn?** Deploy the workshop and start exploring! 🚀","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabricks-solutions%2Fmcp-workshop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatabricks-solutions%2Fmcp-workshop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabricks-solutions%2Fmcp-workshop/lists"}