custom-mcp-server

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.

Related MCP server: Enterprise MCP Gateway and Tool Registry

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

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:

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.

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