Super-I-Tech/mcp_plexus

Build powerful, scalable, and secure Model Context Protocol (MCP) applications with ease. MCP Plexus is a Python framework built on the robust jlowin/fastmcp (FastMCP 2.7) library, designed to empower developers to deploy multi-tenant MCP servers that seamlessly integrate with external services via OAuth 2.1 and manage API key access for tools.
---
Introduction
What is MCP Plexus?
MCP Plexus extends the capabilities of FastMCP 2.7, providing a structured environment for creating sophisticated, multi-tenant AI backend systems. It allows you to define distinct, isolated environments (tenants) that can expose customized sets of tools, resources, and prompts to Large Language Models (LLMs) and AI agents.
**Key differentiating features include:**
- **Robust Multi-Tenancy:** Host multiple clients or organizations on a single deployment, each with their own data and tool access.
- **Simplified External Service Integration:** Securely connect your MCP tools to external OAuth 2.1 protected services (like GitHub, Google APIs, etc.) with built-in flow management.
- **User-Specific Persistent Access:** Enable host applications to register their users with Plexus, allowing for persistent storage of external OAuth tokens, reducing re-authentication friction.
- **API Key Management for Tools:** Securely store and inject API keys for tools that require direct key-based authentication to external services.
- **Standardized and Extensible:** Leverages the full power of FastMCP's Pythonic decorators for defining MCP components, while providing a clear structure for extension.
Why MCP Plexus?
As AI applications grow in complexity, the need to securely provide LLMs with relevant context and executable capabilities becomes paramount. MCP Plexus addresses this by:
- **Simplifying Multi-Tenant Deployments:** Reduces the boilerplate and complexity of managing multiple, isolated MCP environments.
- **Standardizing External API Access:** Provides a consistent and secure mechanism for tools to interact with OAuth-protected and API key-gated services.
- **Enhancing User Experience:** Through persistent user authentication and token storage, it minimizes repeated login prompts to external services.
- **Promoting Secure Practices:** Manages sensitive credentials (OAuth tokens, API keys) outside of your core tool logic.
- **Leveraging FastMCP Power:** Builds upon the proven, high-performance FastMCP 2.7 library for core MCP protocol handling and its developer-friendly interface.
Core Philosophy
- **Security First:** Designed with OAuth 2.1 and secure credential management at its core.
- **Developer Experience:** Aims for an intuitive API for defining tenants, tools, and secure integrations.
- **Scalability & Isolation:** Built for multi-tenant architectures with clear separation of concerns.
- **Extensibility:** Provides a foundation that can be extended with custom authentication providers and services.
---
Key Features
- **Multi-Tenancy:**
- Support for multiple isolated tenants identified via URL paths (e.g., /{entity_id}/mcp/).
- Tenant-specific MCP session management (currently using Redis by default).
- (Planned) Tenant-specific configuration for tool visibility and provider settings.
- **Plexus User Authentication:**
- Host applications can register their users with MCP Plexus via a secure endpoint (/{entity_id}/plexus-auth/register-user).
- Obtain a plexus_user_auth_token that links the host application's user to a persistent identity within Plexus.
- Enables persistent storage of external OAuth tokens and API keys scoped to the user.
- **External OAuth 2.1 Flow Facilitation for Tools:**
- The @requires_auth(provider_name, scopes) decorator for MCP tools triggers an OAuth 2.1 Authorization Code Grant with PKCE flow for external providers (e.g., GitHub).
- Manages OAuth callbacks, token exchange, and secure token storage (session-bound for guest users, persistently against persistent_user_id for authenticated Plexus users).
- Tools receive an authenticated httpx.AsyncClient via the PlexusContext for interacting with the external provider.
- Administrative CLI/API for managing tenant-specific configurations of external OAuth providers (e.g., client ID/secret for GitHub).
- **API Key Management for Tools:**
- The @requires_api_key(provider_name, key_name_display, instructions) decorator for MCP tools.