A production-ready accelerator for building MCP servers on Databricks Apps:
expose any Databricks capability as tools for AI agents.

Quickstart · Architecture · Configuration · Deployment · Documentation

---

What is this?

An accelerator that turns a Databricks workspace into an agent-ready backend. Anything running in Databricks (a Genie space, an Agent Framework/Agent Bricks agent on Model Serving, a SQL warehouse, any SDK-reachable capability) becomes an MCP tool: discoverable and callable by every MCP client (Claude, AI Playground, Copilot Studio agents in Teams, custom agents), with no client-side changes.

The core (what you build on):

• MCP server (FastMCP + FastAPI) serving tools over streamable HTTP at /mcp; add a tool by writing one decorated Python function (guide)
• Databricks Apps deployment: service-principal and end-user OAuth handled by the platform, secrets injected as app resources, guided by a Claude Code deploy skill
• Production scaffolding: hermetic test suite covering every tool, enforced coding standards, resilient startup (optional integrations degrade gracefully, never crash the server)

The included example (a complete tool + channel, end to end):

• ask_genie tool: natural-language data Q&A via a Genie space, with caller-owned conversation continuity
• Slack bot: the same Genie capability surfaced to humans: /askgenie, DMs, and @mentions, with automatic chart generation from query results

The example is a working reference, not the product: keep it, adapt it, or replace it with your own tools; the structure is what the accelerator delivers.

Architecture

The diagram shows the accelerator with the included example wired in. The Databricks App box is the reusable core; the Genie space and Slack lane are the example capability and channel:

Full component and auth model breakdown: docs/architecture.md

MCP tools

Tool	Auth	Kind	Description
health	none	core	Liveness check
get_current_user	end user (forwarded OAuth token)	core	Identity of the calling user
ask_genie	app service principal	example	Conversational data Q&A against a Genie space

Your own tools slot in beside these: one decorated function each, automatically discovered by clients and covered by the tests. To wrap a Databricks-hosted agent as a tool, follow the recipe.

As part of the example, the Slack surface answers the same Genie questions in-channel, formatted as Block Kit with an auto-generated chart (line/pie/bar chosen from the result shape).

Quickstart

Prerequisites: Python 3.11+, uv, Databricks CLI (authenticated).

uv sync

# Example configuration (all optional; the server runs without it:
# ask_genie returns a config error and the Slack bot stays disabled).
# See docs/setup-secrets.md for where these values come from.
export GENIE_SPACE_ID="<genie-space-id>"
export SLACK_BOT_TOKEN="xoxb-..."
export SLACK_APP_TOKEN="xapp-..."

uv run custom-mcp-server        # → http://localhost:8000/mcp
uv run pytest tests/            # integration tests: discovers and calls every tool

Configuration

No secrets live in this repo. app.yaml resolves configuration from Databricks App resources (valueFrom:); locally they are plain environment variables. The pattern is the accelerator's contract: the current entries belong to the included example, and your own tools' configuration follows the same shape:

Env var	Deployed source (resource key)	Used by
GENIE_SPACE_ID	genie-space	example: Genie space to query
SLACK_BOT_TOKEN	slack-bot-token	example: Slack bot token (xoxb-…)
SLACK_APP_TOKEN	slack-app-token	example: Slack Socket Mode token (xapp-…)

Full setup (Slack app creation, secret scopes, resource binding): docs/setup-secrets.md

Deployment

With Claude Code (recommended): the repo ships a deploy skill covering the full checklist: prerequisites, secrets, app creation, resource bindings, deploy, verification. Open the repo in Claude Code and ask it to "deploy this app".

Manually: databricks apps create → databricks sync → databricks apps deploy; see docs/deployment.md, including verification steps and AI Playground testing.

Project structure

server/            # MCP server + Slack bot (see docs/architecture.md)
scripts/dev/       # Local server, remote OAuth testing, token generation
tests/             # Integration tests (auto-cover every registered tool)
docs/              # Documentation (architecture, setup, deployment, testing)
.claude/           # Claude Code deploy skill + skill-sync hook
app.yaml           # Databricks Apps runtime config (secrets via valueFrom)

Documentation

Full wiki index: docs/, organized as Understand → Set up → Deploy → Integrate → Extend.

Page	Contents
Architecture	Components, request flows, authentication model
Secrets & Configuration	Slack app setup, Databricks secrets, app resource binding
Deployment	Claude Code skill, manual CLI deploy, verification, AI Playground
Testing	Integration tests, remote OAuth testing, token generation
Teams via Copilot Studio	Step-by-step: publish a Teams agent backed by this server
Teams design & roadmap	Why Teams ≠ Slack, integration options, phased plan
Adding tools	Tool development guide and conventions

AI assistants working on this codebase: see Claude.md.

Development

uv run ruff format .        # format
uv run ruff check .         # lint
uv run pytest tests/        # integration tests