https://github.com/ithena-one/mcp-governance-sdk
Enterprise Governance Layer (Identity, RBAC, Credentials, Auditing, Logging, Tracing) for the Model Context Protocol SDK
https://github.com/ithena-one/mcp-governance-sdk
ai audit compliance credential-manager credentials enterprise governance identity identity-management llm logging mcp-server modelcontextprotocol open-telemetry rbac rbac-management sdk tracing w3c
Last synced: 5 months ago
JSON representation
Enterprise Governance Layer (Identity, RBAC, Credentials, Auditing, Logging, Tracing) for the Model Context Protocol SDK
- Host: GitHub
- URL: https://github.com/ithena-one/mcp-governance-sdk
- Owner: ithena-one
- License: apache-2.0
- Created: 2025-03-28T01:30:56.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-04-04T03:45:08.000Z (6 months ago)
- Last Synced: 2025-05-07T03:15:06.145Z (5 months ago)
- Topics: ai, audit, compliance, credential-manager, credentials, enterprise, governance, identity, identity-management, llm, logging, mcp-server, modelcontextprotocol, open-telemetry, rbac, rbac-management, sdk, tracing, w3c
- Language: TypeScript
- Homepage: https://ithena.one
- Size: 623 KB
- Stars: 24
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- Security: docs/security.md
Awesome Lists containing this project
README
# MCP Governance SDK (@ithena-one/mcp-governance)
[](https://www.npmjs.com/package/@ithena-one/mcp-governance)
[](https://www.npmjs.com/package/@ithena-one/mcp-governance)
[](https://opensource.org/licenses/Apache-2.0)
[](https://x.com/andellvan)
**Website:** [ithena.one](https://ithena.one)
**The missing governance layer for your Model Context Protocol (MCP) servers.**
Build secure, compliant, and observable MCP applications with [Ithena](https://ithena.one). Easily add **Identity, Authorization (RBAC), Credential Management, Auditing, Logging, and Tracing** using our SDK for servers built with [`@modelcontextprotocol/typescript-sdk`](https://github.com/modelcontextprotocol/typescript-sdk), or leverage the upcoming **Ithena Managed Platform** (waitlist open!).
---
**📚 Documentation:**
* **[Getting Started](./docs/getting-started.md)** - Quick start guide with a complete example
* **[Tutorial: Identity & RBAC](./docs/tutorial.md)** - Step-by-step guide to implementing core governance features
* **[Core Concepts](./docs/core-concepts.md)** - Understanding the SDK's architecture and pipeline
* **[Configuration](./docs/configuration.md)** - All available options and their usage
* **[Interfaces](./docs/interfaces.md)** - Extensibility points and custom implementations
* **[Authorization](./docs/authorization.md)** - RBAC system and permission management
* **[Auditing & Logging](./docs/auditing-logging.md)** - Observability and compliance features
* **[Default Implementations](./docs/defaults.md)** - Built-in components (development only)
* **[Security Considerations](./docs/security.md)** - Security best practices and warnings
---
## The Problem: Production MCP Needs More
The standard [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) is excellent for implementing the core MCP communication protocol. However, deploying MCP servers in production, especially in enterprise environments, requires addressing critical governance questions:
* ❓ **Who** is accessing data and tools? (Authentication)
* 🔒 Are they **allowed** to do that? (Authorization)
* 🔑 How do handlers securely access needed **secrets**? (Credentials)
* 📝 **What happened**? (Auditing & Compliance)
* 🩺 How do we **monitor and debug** effectively? (Logging & Tracing)
Implementing these consistently across every MCP server is complex and error-prone.
## The Solution: `@ithena-one/mcp-governance`
This SDK provides a standard, pluggable framework that wraps the base `Server` class, letting you integrate essential governance features without rewriting your core MCP logic.
Ithena offers two ways to achieve this: the **open-source SDK** (`@ithena-one/mcp-governance`) for self-hosting, and the upcoming **Ithena Managed Platform** (currently accepting users via a [waitlist](https://ithena.one#platform)) which provides hosted, production-ready backends for the SDK's interfaces, eliminating infrastructure management.
**Benefits:**
* ✅ **Standardize Governance:** Consistent handling of identity, permissions, secrets, and auditing.
* 🔒 **Enhance Security:** Enforce access controls and securely manage credentials.
* 📝 **Meet Compliance:** Generate detailed audit trails for regulatory requirements.
* 🧩 **Pluggable Architecture:** Integrate easily with your existing enterprise systems (IDPs, Secret Managers, SIEMs) via well-defined interfaces. (See **[Interfaces](./docs/interfaces.md)**)
* ⚙️ **Focus on Business Logic:** Let the SDK handle governance boilerplate, allowing your team to focus on building valuable MCP resources, tools, and prompts.
* 🚀 **Faster Development:** Get production-ready features out-of-the-box with sensible defaults for development and testing. (See **[Defaults](./docs/defaults.md)**)
* ☁️ **Optional Managed Platform:** Skip infrastructure setup and management by using the Ithena Managed Platform (join the [waitlist](https://ithena.one#platform)!).
## Key Features
* 🆔 **Pluggable Identity Resolution** (`IdentityResolver`)
* 🛡️ **Flexible Role-Based Access Control** (`RoleStore`, `PermissionStore`)
* 🔑 **Secure Credential Injection** (`CredentialResolver`)
* ✍️ **Comprehensive Auditing** (`AuditLogStore`)
* 🪵 **Structured, Request-Scoped Logging** (`Logger`)
* 🔗 **Trace Context Propagation** (W3C default via `TraceContextProvider`)
* ⚙️ **Configurable Governance Pipeline** (See **[Core Concepts](./docs/core-concepts.md)**)
* 📦 **Minimal Intrusion** (Wraps the base SDK `Server`)
## Architecture Overview
`@ithena-one/mcp-governance` intercepts incoming MCP requests and notifications, processing them through a defined pipeline before (or during) the execution of your business logic handlers.
```mermaid
graph LR
A[MCP Request In] --> B(Context Setup: EventID, Logger, TraceContext);
B --> C{IdentityResolver?};
C -- Yes --> D[Resolve Identity];
C -- No --> E[Identity = null];
D --> E;
E --> F{RBAC Enabled?};
F -- No --> K[Credential Resolution];
F -- Yes --> G{Identity Resolved?};
G -- No --> H(DENY: Identity Required);
G -- Yes --> I[Derive Permission];
I --> J{Permission Check Needed?};
J -- No (null permission) --> L{Post-Auth Hook?};
J -- Yes --> J1[Get Roles];
J1 --> J2[Check Permissions];
J2 -- Denied --> H2(DENY: Insufficient Permission);
J2 -- Granted --> L;
L -- Yes --> M[Execute Hook];
L -- No --> K;
M --> K;
K -- Yes (Resolver Exists) --> N[Resolve Credentials];
K -- No --> O[Credentials = null/undefined];
N -- Error & failOnError=true --> P(FAIL: Credentials Error);
N -- Error & failOnError=false --> O;
N -- Success --> O;
O --> Q[Execute Governed Handler];
Q -- Success --> R[Result];
Q -- Error --> S(FAIL: Handler Error);
R --> T(Send Response);
S --> T;
P --> T;
H --> T;
H2 --> T;
T --> U(Audit Log);
style H fill:#f99,stroke:#333,stroke-width:2px;
style H2 fill:#f99,stroke:#333,stroke-width:2px;
style P fill:#f99,stroke:#333,stroke-width:2px;
style S fill:#f99,stroke:#333,stroke-width:2px;
style U fill:#ccf,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
```
See **[Core Concepts](./docs/core-concepts.md)** for more details on the pipeline.
The SDK defines interfaces (like `IdentityResolver`, `AuditLogStore`, etc.). You can implement these yourself or use clients connecting to the **Ithena Managed Platform** (waitlist open) for a hosted solution.
## SDK vs. Managed Platform
Ithena offers flexibility in how you implement MCP governance:
1. **`@ithena-one/mcp-governance` SDK (Open Source):**
* Provides the core `GovernedServer`, pipeline, and governance interfaces (`IdentityResolver`, `RoleStore`, `AuditLogStore`, etc.).
* You implement the backend logic for these interfaces, integrating with your existing systems (databases, secret managers, SIEMs).
* **Use Case:** Full control over infrastructure, integrating deeply with bespoke internal systems. Requires infrastructure management.
2. **Ithena Managed Platform (Waitlist Open):**
* A hosted cloud service providing production-ready, scalable backend implementations for the SDK's interfaces via simple API clients.
* Use the same SDK, but configure it to point to the Ithena Platform APIs instead of your own backends.
* **Use Case:** Faster time-to-market, reduced operational burden, focus purely on MCP application logic.
* ➡️ **[Join the Waitlist](https://ithena.one#platform)**
You choose the approach that best fits your needs. The SDK seamlessly supports both self-hosted and platform-based backends.
## Installation
```bash
npm install @ithena-one/mcp-governance @modelcontextprotocol/sdk zod
# or
yarn add @ithena-one/mcp-governance @modelcontextprotocol/sdk zod
# or
pnpm add @ithena-one/mcp-governance @modelcontextprotocol/sdk zod
```
**Peer Dependencies:** Make sure you have compatible versions of `@modelcontextprotocol/sdk` (check `peerDependencies` in `package.json`) and `zod` installed.
## Quick Start
See the **[Getting Started Guide](./docs/getting-started.md)** for a runnable example.
## Next Steps
* Understand the **[Core Concepts](./docs/core-concepts.md)** like `GovernedServer` and the pipeline.
* Review the **[Configuration Options](./docs/configuration.md)** available.
* Explore the **[Interfaces](./docs/interfaces.md)** to integrate with your systems.
* Learn about **[Authorization](./docs/authorization.md)** and **[Auditing/Logging](./docs/auditing-logging.md)**.
* Review the **[Security Considerations](./docs/security.md)** carefully.
## Contributing
Contributions are welcome! Please open an issue or submit a pull request on the [GitHub repository](https://github.com/ithena-one/mcp-governance-sdk).
## License
This project is licensed under the Apache-2.0 License. See the [LICENSE](LICENSE) file for details.