Ticket Queue MCP Server & Client

A production-style Model Context Protocol (MCP) solution built for the "Build a Production MCP Server & Client" lab: a server that exposes an internal support ticket queue as MCP tools, resources, and prompts, and a client that discovers and invokes them, over Streamable HTTP with OAuth 2.1 authorization.

What's here

server/           MCP server (FastMCP): tools, resources, prompts, OAuth AS+RS, error handling
  data_store.py   In-memory mock ticket DB + KB articles (stands in for a real ticketing system)
  auth.py         OAuth 2.1 Authorization Server configuration (scopes, DCR)
  app.py          The FastMCP server itself -- entry point

client/           MCP client
  oauth_flow.py   Scripted OAuth 2.1 + PKCE flow (headless-friendly demo client)
  client_demo.py  Connects, discovers, and invokes everything -- entry point

docs/
  ARCHITECTURE.md   Diagram + component/transport write-up
  CAPABILITIES.md   Full reference for every tool/resource/prompt
  SECURITY.md       Security design summary (Requirement #7)

demo/
  run_demo.sh     Starts the server, runs the client, captures output
  demo_log.txt    A captured successful run (discovery -> invocation -> elicitation -> errors)

Related MCP server: DeskCrew MCP Server

Quickstart

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

bash demo/run_demo.sh

This starts the server on http://127.0.0.1:8000, runs the client through the full OAuth handshake, discovery, and invocation flow, and writes the transcript to demo/demo_log.txt.

To run the pieces separately:

# terminal 1
python3 -m server.app

# terminal 2
python3 -m client.client_demo

What the demo actually shows

client/client_demo.py runs, in order:

1. Two OAuth 2.1 + PKCE token acquisitions -- one client requesting only tickets:read, one requesting tickets:read tickets:write.

2. Full discovery: tools/list, resources/list, resources/templates/list, prompts/list.

3. A tool call (search_tickets, get_ticket), a resource read (a KB article, the queue summary), and a prompt fetch (triage_ticket).

4. A write action (add_comment).

5. The high-impact close_ticket action, once with the elicitation confirmed and once declined, showing both outcomes.

6. The read-only client attempting a write tool, demonstrating least-privilege scope enforcement.

7. Both required error-handling failure modes: an invalid ticket ID, and a simulated unreachable backing data source, both surfaced as clean, non-leaky messages.

See demo/demo_log.txt for the full captured transcript, and docs/SECURITY.md for the reasoning behind each of these design choices.

Requirements coverage

Built with

Model Context Protocol / FastMCP (Python).