MCP-Server-with-Authentication-and-Testing-with-Inspector

ahmad-act/MCP-Server-with-Authentication-and-Testing-with-Inspector

3.3

If you are the rightful owner of MCP-Server-with-Authentication-and-Testing-with-Inspector and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

This project implements a Model Context Protocol (MCP) server with authentication mechanisms and testing capabilities using the MCP Inspector.

🚀 MCP Server with Authentication and Testing with Inspector

This project implements a Model Context Protocol (MCP) server with two authentication mechanisms: API Key Authentication and JWT (JSON Web Token) Authentication. It provides a robust framework for handling authenticated requests with comprehensive error handling and logging, suitable for production environments. The server supports tools like echo, login, secure_action, and admin_action, with authentication enforced where required.

📚 Table of Contents

  1. 🚀 Project Overview

  2. 🎯 Purpose

  3. ✨ Features

  4. 🗂️ Project Structure

  5. ✅ Prerequisites

  6. ⚙️ Installation

  7. 🧩 Packages

  8. 🚦 Usage

  9. 🔄 Workflow

  10. 🩵 Troubleshooting

🎯 Purpose

The purpose of this project is to demonstrate secure MCP server implementations with two distinct authentication methods:

  • 🔑 API Key Authentication: Validates requests using predefined API keys.
  • 🛡️ JWT Authentication: Uses JSON Web Tokens for user authentication and permission-based access control.

This project is designed for developers who need a secure, scalable, and extensible MCP server with robust debugging and logging capabilities.

✨ Features

  • 🔑 API Key Authentication:

    • Validates requests using a set of predefined API keys.
    • Supports key extraction from arguments, metadata, or environment variables.
    • Simple echo tool for demonstration.

  • 🛡️ JWT Authentication:

    • Supports user authentication via username/password to generate JWT tokens.
    • Enforces permission-based access control (read, write, admin).
    • Includes tools: login, echo, secure_action, and admin_action.
    • Configurable token expiry (default: 24 hours).
    • Token extraction from arguments, metadata, or environment variables.

  • ⚠️ Robust Error Handling:

    • Custom McpError for consistent error responses.
    • Detailed logging of errors and server events.

  • 📝 Logging:

    • Configurable logging to both console and rotating log files.
    • Log rotation based on file size (5MB, with 5 backups).
    • Automatic cleanup of old log files based on age.

  • 🔍 MCP Inspector Integration:

    • Compatible with MCP Inspector for testing and debugging.
    • Supports debugging via --debug flag.

🗂️ Project Structure

/
├── src/
│   ├── config/
│   │   ├── __init__.py
│   │   ├── app_settings.py                     # Configuration for environment variables and settings
│   │   └── logging_config.py                   # Logging setup with file rotation
│   ├── mcp-server-with-stdio-api-key-auth.py   # API Key Authentication server
│   ├── mcp-server-with-stdio-auth2-auth.py     # To Do
│   └── mcp-server-with-stdio-jwt-key-auth.py   # JWT Authentication server
├── pyproject.toml                              # Project documentation
└── README.md                                   # Python dependencies

✅ Prerequisites

  • Python: Version 3.13 or higher
  • uv: Used for managing Python virtual environments
  • Node.js: Required for running MCP Inspector
  • NPM: Required to run MCP Inspector
  • Operating System: Windows, macOS, or Linux

⚙️ Installation

  1. 📥 Clone the Repository:

    git clone https://github.com/ahmad-act/MCP-Server-with-Authentication-and-Testing-with-Inspector.git
cd MCP-Server-with-Authentication-and-Testing-with-Inspector

  2. 🪄 Set Up a Virtual Environment (recommended):

    uv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. 📦 Install Dependencies:

    uv sync

🧩 Packages

The following Python packages are required:

mcp[cli]>=1.10.1
PyJWT>=2.8.0
python-dotenv>=1.0.0

👉 Install them using:

uv add mcp[cli] PyJWT python-dotenv

🚦 Usage

1️⃣ MCP Server with Stdio and API Key (mcp-server-with-stdio-api-key-auth.py)

▶️ Run the MCP Server:

⚠️ You do not need to manually run the MCP server for stdio transport. MCP Inspector runs the MCP Server for stdio transport.

▶️ Run the MCP Inspector:

The stdio server is typically launched by the MCP Inspector, not manually. Run the Inspector with the following command, add -e environment variable and adjusting the --directory path to your src/ directory:

npx @modelcontextprotocol/inspector uv -e MCP_API_KEY=sk-1234567890abcdef --directory '<your-src-directory>/src' run mcp-server-with-stdio-api-key-auth.py --debug

🌐 Open the MCP Inspector:

Open the link http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=XXXXXXXXXXXXXXXXXX with its token in your browser:

🧪 Using the MCP Inspector

  1. After running the above command, the Inspector will start and automatically connect to the stdio-based server.

  2. In the Inspector UI (http://127.0.0.1:6274), inspect the available tools (e.g., echo).

  3. Test the echo tool:

    • Input:
    {
  "method": "call_tool",
  "params": {
    "name": "echo",
    "arguments": {
      "message": "test",
      "_api_key": "sk-1234567890abcdef"
    }
  }
}

    Expected Response:

    {
  "result": [
    {
      "type": "text",
      "text": "Echo: test"
    }
  ]
}

2️⃣ MCP Server with Stdio and API Key (mcp-server-with-stdio-jwt-key-auth.py)

▶️ Run the MCP Server:

⚠️ You do not need to manually run the MCP server for stdio transport. MCP Inspector will launch the server automatically.

▶️ Run the MCP Inspector:

The stdio server is typically launched by the MCP Inspector, not manually. Run the Inspector with the following command, adjusting the --directory path to your src/ directory:

npx @modelcontextprotocol/inspector uv --directory '<your-src-directory>\src' run mcp-server-with-stdio-jwt-key-auth.py --debug

🌐 Open the MCP Inspector:

Open the link http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=XXXXXXXXXXXXXXXXXX with its token in your browser:

🧪 Using the MCP Inspector

  1. After running the above command, the Inspector will start and automatically connect to the stdio-based server.

  2. Usage Flow:

    • Step 1: Login to Get JWT Token:

      {
  "method": "call_tool",
  "params": {
    "name": "login",
    "arguments": {
      "username": "user1",
      "password": "password123"
    }
  }
}

      Response:

      {
  "result": [
    {
      "type": "text",
      "text": "Login successful! JWT Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  ]
}

    • Step 2: Use JWT Token for Authenticated Requests:

      {
  "method": "call_tool",
  "params": {
    "name": "echo",
    "arguments": {
      "message": "test",
      "_jwt_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}

      Response:

      {
  "result": [
    {
      "type": "text",
      "text": "Echo (authenticated as user1): test"
    }
  ]
}

3️⃣ MCP Server with Stdio and Auth2 (mcp-server-with-stdio-auth2-auth.py)

🚧 To Do

🔄 Workflow

  1. 🔑 API Key Authentication:

    • The server checks for a valid API key in the request arguments, metadata, or environment variables.
    • If valid, the request is processed; otherwise, an error is returned.
    • The echo tool demonstrates basic functionality.

  2. 🛡️ JWT Authentication:

    • Users first call the login tool with valid credentials to obtain a JWT token.
    • The token is used in subsequent requests for tools like echo, secure_action, or admin_action.
    • Permissions (read, write, admin) are checked for each tool.
    • Tokens expire after 24 hours (configurable).

  3. 📝 Logging:

    • Logs are written to both the console and a rotating log file in the logs directory.
    • Old log files are cleaned up based on a specified retention period.

  4. 🔍 Testing with MCP Inspector:

    • Use MCP Inspector to interact with the server via a web interface.
    • Debug mode (--debug) provides detailed output for troubleshooting.

🩵 Troubleshooting

  • 🚫 Invalid API Key:

    • Ensure the API key is one of: sk-1234567890abcdef, sk-abcdef1234567890, sk-test123456789.
    • Check environment variable MCP_API_KEY or request arguments.

  • ⚠️ Invalid JWT Token:

    • Verify the token is not expired (valid for 24 hours).
    • Ensure the correct JWT_SECRET is set.
    • Check username/password for login tool.

  • 🔒 Permission Errors:

    • Ensure the user has the required permissions (read, write, or admin) for the requested tool.

  • 📝 Log Files:

    • Check the logs directory for detailed error messages.
    • Logs are named in the format YYYYMM.log.