Skip to main content
Glama

Bella — an enterprise MCP server for Claude

tests

Course repo for "Build an Enterprise MCP Server: Connect Claude to Your Company's Data" by Victor Velázquez.

Bella is the AI data analyst of Brightline Outdoor (a fictional outdoor-gear retailer). She lives behind an MCP server, so you can ask Claude — Desktop, Code or claude.ai — "who were our top Enterprise customers this year?" and get an answer from the company database, safely.

You ─▶ Claude ─▶ MCP ─▶ Bella ─▶ guard ─▶ SQLite (read-only)
                        │  5 tools · 1 resource · 1 prompt
                        └─ auth (none / JWT / GitHub OAuth) · scopes · PII masking · audit · rate limits
  • ✅ Runs with zero API keys: Bella's brain uses your Claude subscription through Claude Code (or an API key, or a free demo mode)

  • ✅ stdio and Streamable HTTP · MCP spec 2026-07-28 via FastMCP 4

  • ✅ OAuth 2.1 resource server · roles → scopes → tools · column-level PII masking

  • ✅ 59 tests, including auth over real HTTP and the stdio transport — CI on every push


Run it in 3 minutes

git clone https://github.com/victor-velazquez-ai/bella-mcp-course.git
cd bella-mcp-course
python -m venv .venv
.venv\Scripts\activate            # macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"
python data/seed.py               # builds data/bella.db (also auto-built on first start)
python verify.py                  # everything green? you're ready

Then connect it to Claude (details and 4 options in docs/connect-to-claude.md):

claude mcp add bella -- python -m bella_mcp        # Claude Code, from the activated venv

Ask: "Using Bella, how did revenue evolve by month this year, and which products are about to run out?"

Related MCP server: SafeSQL

Bella's surface

#

Tool

What

Scope

1

sales_summary

revenue, orders, units, AOV, margin % by month / category / region / channel

bella:read

2

top_customers

top customers by revenue for a period, optional segment

bella:read

3

inventory_alerts

products at/below reorder level, days of cover, suggested reorder

bella:read

4

customer_profile

360° view of one customer (by id, name or email)

bella:read

5

ask_bella

general query: plain English (Bella writes the SQL) or a read-only SELECT

bella:query

Plus the resource bella://schema (schema + business glossary) and the prompt monthly_business_review(month). All tools are annotated readOnlyHint: true and return structured output.

Security: six layers between a prompt and your data

1 scopes      ask_bella needs bella:query — without it the tool is invisible        auth.py
2 shape       exactly one SELECT / WITH statement                                    db.py
3 read-only   SQLite opened with mode=ro                                             db.py
4 authorizer  reads only; emails read as NULL without bella:pii (aliases can't help) db.py
5 limits      200 rows · 2 s timeout · 1 MB values                                   db.py
6 audit       every call → logs/audit.jsonl (who, tool, args, ms, outcome) + rate limit  audit.py

The SQL Bella's own brain writes is treated as untrusted input and goes through the same guard. Try to break it: python lessons/03_attack_the_guard.py.

Auth modes

BELLA_AUTH_MODE

For

How

none (default)

stdio, local dev

local user gets BELLA_LOCAL_ROLE (default analyst)

jwt

tokens from any IdP

signature + issuer + audience + expiry + scopes. Local IdP: python scripts/mint_token.py analyst

github

claude.ai custom connector

full OAuth 2.1 login via GitHub (OAuth proxy, PKCE, discovery metadata)

Roles: viewer (bella:read) · analyst (+ bella:query) · admin (+ bella:pii). Details and Entra ID / Okta / Auth0 / Keycloak setup: docs/auth.md.

Repo map (course Part 2 → files)

Step

Files

P1 setup

pyproject.toml, data/seed.py, verify.py

P2 MCP in 10 lines · what Claude sees

lessons/01_hello_mcp.py, lessons/02_what_claude_sees.py

P3 data layer & SQL guard

src/bella_mcp/db.py, lessons/03_attack_the_guard.py

P4 the 4 presets

src/bella_mcp/server.py

P5 ask_bella + Bella's brain

src/bella_mcp/server.py, src/bella_mcp/brain.py

P6 enterprise layer

src/bella_mcp/auth.py, src/bella_mcp/audit.py, scripts/mint_token.py

P7 connect to Claude

src/bella_mcp/__main__.py, .mcp.json, docs/connect-to-claude.md, Dockerfile

Plan-B demo

lessons/04_bella_tour.py

src/bella_mcp/
  config.py   settings from env (.env)          db.py      the guard (layers 2-5) + schema
  seed.py     builds the demo database          brain.py   English → SQL (Claude API / subscription / OpenAI / demo)
  auth.py     auth modes, roles, scopes         audit.py   audit middleware (layer 6)
  server.py   build_server(): tools, resource, prompt, /health
  __main__.py python -m bella_mcp [stdio|http]

Commands

python -m bella_mcp                        # stdio (Claude Desktop / Code launch this)
python -m bella_mcp http                   # http://localhost:8000/mcp  · health: /health
BELLA_AUTH_MODE=jwt python -m bella_mcp http
python scripts/mint_token.py viewer --decode
python -m pytest -q
docker build -t bella . && docker run -p 8000:8000 bella

Make it yours

Swap the data, keep the architecture, ship it, put it in your portfolio: docs/make-it-yours.md.


Built with FastMCP 4 on the Model Context Protocol. Data is synthetic. MIT licensed. Never commit your .env.

Available Tools

5 tools
ask_bellaAsk BellaA
Read-onlyIdempotent

Ask Bella anything about Brightline Outdoor's data that the preset tools don't cover.

Bella turns plain-English questions into SQL using the company's business definitions, runs it safely (read-only, row and time limits) and returns the rows plus the SQL she used. You may also send a SELECT yourself. Returns at most 200 rows: aggregate in SQL when possible.

Inputs: question (required). Returns: object

customer_profileCustomer ProfileA
Read-onlyIdempotent

A 360° view of one customer: profile, lifetime revenue, orders, favourite category and last 5 orders.

If several customers match a partial name, returns the candidates so you can ask which one.

Inputs: customer (required). Returns: object

inventory_alertsInventory AlertsA
Read-onlyIdempotent

Products at or below their reorder level, most urgent first.

For each: stock, reorder level, units sold in the last 90 days, days of cover left at that pace, and a suggested reorder quantity (enough for ~45 days, at least 2x the reorder level).

Inputs: category. Returns: object

sales_summarySales SummaryA
Read-onlyIdempotent

Revenue, orders, units, average order value and margin %, grouped by month, category, region or channel.

Uses the official revenue definition (completed + shipped orders, net of discounts). Example: "how did revenue evolve this year?" -> group_by="month", start_date="2026-01-01".

Inputs: end_date, group_by, start_date. Returns: object

top_customersTop CustomersA
Read-onlyIdempotent

The customers who generated the most revenue in a period, with order count and last order date.

Optionally filter by segment (Consumer, SMB, Enterprise). Emails are only shown to roles with bella:pii.

Inputs: limit, segment, end_date, start_date. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 5 tools

    Disambiguation4/5

    The four preset tools target clearly distinct resources: revenue over time, ranked customers, low-stock products, and a single customer's 360 view. The only overlap is ask_bella, a free-form SQL tool that could answer anything the presets answer, though its description explicitly scopes it to questions the presets don't cover.

    Naming Consistency5/5

    All five names are lowercase snake_case descriptive noun compounds (sales_summary, top_customers, inventory_alerts, customer_profile, ask_bella). No mixing of conventions, camelCase, or ad-hoc verbs.

    Tool Count5/5

    Five tools is well-scoped for a conversational analytics server: four focused presets plus one general query fallback. Each tool clearly earns its place and there is no bloat.

    Completeness4/5

    Core analytics workflows are covered: revenue trends, customer ranking, customer detail, and inventory reordering, with ask_bella filling any remaining gap (e.g. product-level, order-level, or ad-hoc questions). The catch-all softens what would otherwise be notable gaps, though agents must fall back to free-form SQL for anything outside these four lenses.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to connect to and interact with SQLite, SQL Server, PostgreSQL, and MySQL databases through natural language. Supports executing queries, managing tables, exporting data, and storing business insights with authentication options including AWS IAM.
      680 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables Claude Desktop and Claude Code to inspect a Postgres schema and run read-only SQL queries against a demo database through the tools describe_schema and query_readonly. Every proposed query passes the same deterministic guardrails — SELECT-only, allow-listed tables, enforced row limits, statement timeouts and a read-only role — before execution.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables Claude to answer questions about a small business's own data by providing predefined sales, customer, refund, and inventory tools, plus a guarded read-only SQL query tool with audit logging.
      6
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables Claude to answer business questions from a SQL database safely, using read-only queries and bounded summaries, while requiring confirmation and audit logging for order-status changes.
      7
      MIT