Dynamic MCP Server Framework

A flexible, extensible framework for building Model Context Protocol (MCP) servers with modern API key authentication, user management, and dynamic tool sharing.

🚀 Overview

Dynamic MCP Server enables secure, user-aware, and extensible AI tool servers. It supports:

• API key-based authentication (simple, compatible with all MCP clients)
• User management and authorization (MongoDB-backed)
• Session-based, per-user tool loading
• Tool sharing and fine-grained access control
• Extensible HTTP and database layers for downstream projects

🌟 Key Features

• Dynamic Tool Management: Create, delete, and authorize tools at runtime—tools are not limited to static definitions at startup or in code. This enables true runtime extensibility and is a primary differentiator from most other MCP servers.
• User Management: Add, update, delete, and list users; admin bootstrapping; role-based access.
• Tool Sharing: Share tools with other users, manage access levels, and receive real-time updates.
• Modern Auth: Simple API key authentication, MongoDB for authorization.
• Extensibility: Add custom HTTP routes and MongoDB collections in downstream projects.
• Session-based Tool Loading: Tools are loaded per user session, not globally.

🔑 Authentication (API Key)

• Each user is assigned a unique apiKey (generated automatically on user creation).
• To authenticate, clients must provide the apiKey via query parameter OR header:
  • Query Parameter: ?apiKey=your-key or ?apikey=your-key
  • Header: x-apikey: your-key or apikey: your-key
• Streamable HTTP Transport (Modern): /mcp?apiKey=... or /mcp with header
• The server authenticates the user by looking up the apiKey in the database.

🚀 Transport Protocols

Dynamic MCP Server supports both legacy and modern MCP transport protocols:

Streamable HTTP Transport

• Protocol Version: 2025-03-26
• Endpoint: /mcp
• Features: Modern, efficient, single-endpoint design
• Authentication: Query parameter ?apiKey=your-key OR header x-apikey: your-key
• Usage: Recommended for new integrations

� Documentation

• Getting Started
• Transport Protocols
• User Management
• Tool Management & Sharing
• Authentication & Authorization
• Extending the Server (HTTP & DB)
• API Reference
• Examples
• Extending the Server: Creating Handler & Tool Packages
• Test Patterns & Mocking Strategies

Tool Visibility Model: All tools are visible to users by default. Users can hide tools from their view using the hide-tool and unhide-tool actions. See User Management and Tool Management & Sharing for details.

🛠️ Quick Start

See Getting Started for installation and basic usage.

📝 Contributing

Contributions are welcome! See the documentation for more details.

📄 License

MIT

🧩 Handler & Tool Registration (New Pattern)

Tools are now registered via handler packages. Each handler package groups related tools and provides a handler function for tool execution. This is the recommended pattern for extensibility and maintainability.

Example:

const myHandlerPackage = {
  name: "my-domain",
  tools: [
    {
      name: "my-tool",
      description: "A custom tool",
      inputSchema: {
        /* ... */
      },
      handler: { type: "my-domain", config: {} },
      rolesPermitted: ["user", "admin"],
    },
    // ...more tools...
  ],
  handler: async (args, context, config, toolName) => {
    // Dispatch logic based on toolName, if needed


... [View full README on GitHub](https://github.com/scitara-cto/dynamic-mcp-server#readme)