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.
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
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
# | 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.
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.
| 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.
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]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 bellaSwap 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.
This server cannot be deployed
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.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
