This MCP server implements a Customer Analytics workshop scenario with two tools and a single resource for discovery. The compute_account_health tool orchestrates a multi-system workflow that blends internal data (like orders) with external data sources (APIs) and applies a scoring model to output a health assessment and risk reasons. The run_sql tool provides safe, guarded database queries with automatic guardrails such as SELECT-only validation and automatic LIMIT injection. You can discover capabilities via the schema://main resource and use the tools through an authenticated MCP endpoint. The server supports role-based access control (admin, user, readonly) so you can observe how permissions gate tool execution in practice. The HTTP server variant includes real authentication with JWTs and API keys, making it suitable for a production-like workflow while preserving safety constraints.

To use the workflow, request the tools list or call a tool with appropriate parameters. For compute_account_health, supply inputs like segment, windowDays, limit, and includeReasons to tailor the health analysis. For run_sql, craft safe SELECT queries that respect the guardrails and rely on the proxy to inject automatic limits and enforce permissions. Through the MCP client, you can present the available toolsets to an agent (for example, an AI assistant) and have it select and execute appropriate tools for a given business task such as analyzing high-value accounts or extracting schema details for validation.

Prerequisites:

• Node.js 20.9.0 or newer
• pnpm 8.0.0 or newer
• Optional: OPENAI_API_KEY for demo features

Installation steps:

1. Clone the repository: git clone <this-repo> cd mcp-server-workshop-best-practices

2. Install dependencies: pnpm install

3. Start the HTTP MCP server (with real auth) and run the workshop demo: pnpm mcp-http-server

   In a second terminal, run the demo:

   pnpm workshop-demo-http

4. Verify the server is running:

   • Health check: http://localhost:3001/health
   • MCP endpoint: http://localhost:3001/mcp (requires auth)

Notes:

• The exact script names (mcp-http-server, workshop-demo-http) are defined in the repository's package.json scripts. If your environment uses a different script setup, adjust accordingly.
• If you prefer a local npm/npx based approach, you can install and run the workshop package in your environment using the provided mcp-server-workshop-best-practices package name.

Tips and considerations:

• The workshop emphasizes safety: the compute_account_health tool operates with read-only data by default in readonly mode for non-admin roles and enforces automatic LIMITs on queries.
• Authentication patterns include JWT and API keys; ensure your client includes the proper Authorization header to access the MCP endpoint.
• The two tools are designed to be workflow-oriented: use exploration (schema://main) to understand available data structures before running analyses.
• When testing with multiple models, ensure the agent can discover capabilities via the schema resource and select appropriate tools for tasks like health analysis or SQL queries.
• If you encounter guardrail issues (e.g., SELECT-only violations), review the tool permissions and query content to align with the intended safety model.