Telusko Support Chat — MCP with Roles, Scopes & JWT

A customer support desk for an online course platform where learners, support agents, and admins all use the same chat interface. What each person can do is decided entirely by the JWT they carry and the scopes inside it — not by the UI or the prompt.

Built as part of the Telusko Agentic AI Engineering with Python course (session 11-10-2026).

Tech stack: Python + FastAPI + MCP (Model Context Protocol) + LangChain + OpenAI + SQLite + JWT + Docker

The One Idea

There is a single chat endpoint and a single model. Nothing in the chat code knows what a learner may do. The difference between Rahul asking “show me my courses” and Akshay asking the same question is the JWT attached to the request, and the MCP server reading the scopes inside it. The permission system is not in the UI and not in the prompt. It is in the server.

Related MCP server: Corebee MCP Server

Roles

Architecture

flowchart LR
    Browser["Browser<br/>http://localhost:8000"] -->|JWT| Backend["FastAPI Backend<br/>:8000"]
    Backend -->|Same JWT| MCP["MCP Server<br/>:8001"]
    MCP --> Tools["Tools<br/>(filtered by scopes)"]
    Tools --> DB[("SQLite<br/>telusko.db")]
    Backend --> LLM["ChatOpenAI"]

• The browser never talks to the MCP server. It only talks to the backend.

• The backend forwards the same JWT to the MCP server on every tool call.

• The MCP server verifies the token and only exposes / allows tools the caller has scopes for.

Features

• Role-based access control via scopes (resource:action) carried in the JWT

• MCP middleware that hides tools the caller cannot use and blocks unauthorized calls

• Data-level rules (e.g. learners can only see their own tickets)

• Full tool-calling loop with a visible trace in the UI (great for learning)

• Simulated course purchase flow

• Admin user management panel (custom permissions possible)

• Fully containerized with Docker Compose

Quick Start

With Docker (recommended)

git clone https://github.com/yash9614/project_mcp.git
cd project_mcp

# Create .env from the example and fill in your values
cp .env.example .env
# Edit .env: add OPENAI_API_KEY and a JWT_SECRET (32+ chars)

docker compose up --build

Open http://localhost:8000

Without Docker

uv sync
uv run python -m database.db          # create + seed the database (once)
uv run python -m mcp_server.server   # MCP server on :8001
uv run python -m backend.app         # Backend + UI on :8000

Demo Accounts

Password for all: password123

Project Structure

.
├── backend/          # FastAPI app, login, chat loop, admin endpoints
├── common/           # config, auth (JWT), permissions, prompts
├── database/         # schema.sql, seed.sql, models.py, db.py
├── mcp_server/       # MCP server: JWT verifier, middleware, tools
├── frontend/         # Single-file HTML UI
├── docker-compose.yml
├── Dockerfile
└── pyproject.toml

Key Design Decisions

• Scopes travel in the JWT. The MCP server never looks up the user in the database to decide permissions — it only trusts the verified token.

• Tool visibility is filtered. tools/list only returns tools the caller has a scope for.

• One client per request. The backend opens a fresh MCP connection for each chat turn, authenticated with that user’s JWT.

• Models layer owns all SQL. Tools never write raw SQL; they call methods on the dataclass models.

• SQLite for simplicity. No external database required for the class project. Moving to Postgres later only requires changing database/db.py.

What to Try

1. Log in as Rahul (learner) → ask about your courses / certificate / failed payment.

2. Log in as Neha (support) → list open tickets, look up Priya, try extending access by 60 days (blocked).

3. Log in as Akshay (admin) → issue a certificate, view stats, open Manage Users.

Watch the tool-call traces under each assistant reply — they show exactly which MCP tools were invoked and what they returned.

Bonus Material

See CONCEPTS.md for the most important concepts and interview-style questions.