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 as a query parameter (e.g., /sse?apiKey=...).
- The server authenticates the user by looking up the apiKey in the database.

---

📚 Documentation

- Getting Started
- 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
  },
};
const server = new DynamicMcpServer({ name: "my-mcp", version: "1.0.0" });

await server.start();

await server.registerHandler(myHandlerPackage);

See Getting Started and Examples for more details.

---

🧩 Tool Argument Mapping (config.args)

When defining a tool, you can use the config.args field to map user-supplied tool options (from inputSchema) to the arguments your action handler expects. This mapping supports:

- Literal values (e.g., "country": "US")
- Template variables (e.g., "city": "{{location}}")
- Nested objects and arrays (all templates are resolved recursively)

Example:

handler: {
  type: "weather-tools",
  config: {
    url: "https://api.openweathermap.org/data/2.5/weather",
    args: {
      queryParams: {
        appid: "{{OPENWEATHER_API_KEY}}",
        q: "{{location}}",
        units: "{{units}}"
      }
    }
  }
}

When the tool is called, the system automatically resolves all {{...}} templates in config.args using the tool input and environment variables. The handler receives the merged and resolved arguments—no manual mapping is needed.

See Tool Authoring for full details and examples.

---