Bella
Supports JWT authentication using Auth0-issued tokens, validating signature, issuer, audience, expiry, and scopes for role-based tool access.
Supports OAuth 2.1 authentication via GitHub for remote MCP connectors, including PKCE and discovery metadata.
Supports JWT authentication using Keycloak-issued tokens, validating signature, issuer, audience, expiry, and scopes for role-based tool access.
Supports JWT authentication using Okta-issued tokens, validating signature, issuer, audience, expiry, and scopes for role-based tool access.
Provides read-only, guarded access to a SQLite company database, exposing sales summaries, top customers, inventory alerts, customer profiles, and read-only English/SELECT queries, with a schema resource, PII masking, row/time/size limits, audit logging, and rate limiting.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Bella Using Bella, show revenue by month this year and which products are low on stock"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Bella — an enterprise MCP server for Claude
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 readyThen 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 venvAsk: "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 |
| revenue, orders, units, AOV, margin % by month / category / region / channel |
|
2 |
| top customers by revenue for a period, optional segment |
|
3 |
| products at/below reorder level, days of cover, suggested reorder |
|
4 |
| 360° view of one customer (by id, name or email) |
|
5 |
| general query: plain English (Bella writes the SQL) or a read-only SELECT |
|
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.pyThe 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
| For | How |
| stdio, local dev | local user gets |
| tokens from any IdP | signature + issuer + audience + expiry + scopes. Local IdP: |
| 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 |
|
P2 MCP in 10 lines · what Claude sees |
|
P3 data layer & SQL guard |
|
P4 the 4 presets |
|
P5 |
|
P6 enterprise layer |
|
P7 connect to Claude |
|
Plan-B demo |
|
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 bellaMake 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 toolsask_bellaAsk BellaARead-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 ProfileARead-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 AlertsARead-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 SummaryARead-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 CustomersARead-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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
GA4, Google Ads and Search Console in Claude. Read-only OAuth, multi-account for agencies.
Read-only Google Ads, GA4 and Search Console data for Claude, with no Google Cloud setup.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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 npmMIT
- AlicenseAqualityCmaintenanceEnables 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.2MIT
- AlicenseAqualityCmaintenanceEnables 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.6MIT
- AlicenseAqualityCmaintenanceEnables 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.7MIT