<div align="center">

<img src="assets/logo.svg" alt="MCP Server Accelerator" width="400"/>

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

[Quickstart](#quickstart) · [Architecture](#architecture) · [Configuration](#configuration) · [Deployment](#deployment) · [Documentation](#documentation)

</div>

---

## 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](https://github.com/jlowin/fastmcp) + FastAPI) serving tools over streamable HTTP at `/mcp`; add a tool by writing one decorated Python function ([guide](docs/adding-tools.md))
- **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](.claude/skills/deploy-accelerator/SKILL.md)
- **Production scaffolding**: hermetic test suite covering every tool, enforced [coding standards](.claude/skills/python-standards/SKILL.md), 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](https://docs.databricks.com/aws/en/genie/), 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:

<div align="center">
  <img src="assets/architecture.svg" alt="High-level architecture: AI assistants and Slack users connect to the Databricks App, which hosts the FastMCP server and Slack bot; both query a Genie Space backed by a SQL Warehouse and Unity Catalog." width="900"/>
</div>

Full component and auth model breakdown: [docs/architecture.md](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](docs/adding-tools.md#recipe-wrap-a-databricks-hosted-agent-as-a-tool).

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](https://github.com/astral-sh/uv), [Databricks CLI](https://docs.databricks.com/aws/en/dev-tools/cli/) (authenticated).

```bash
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`](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](docs/setup-secrets.md)**

## Deployment

**With Claude Code (recommended):** the repo ships a [deploy skill](.claude/skills/deploy-accelerator/SKILL.md) 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](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/](docs/README.md)**, organized as Understand → Set up → Deploy → Integrate → Extend.

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

AI assistants working on this codebase: see [Claude.md](Claude.md).

## Development

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