MCP Governance SDK (@ithena-one/mcp-governance)

Website: ithena.one

The missing governance layer for your Model Context Protocol (MCP) servers.

Build secure, compliant, and observable MCP applications with Ithena. Easily add Identity, Authorization (RBAC), Credential Management, Auditing, Logging, and Tracing using our SDK for servers built with @modelcontextprotocol/typescript-sdk, or leverage the upcoming Ithena Managed Platform (waitlist open!).

---

📚 Documentation:

• Getting Started - Quick start guide with a complete example
• Tutorial: Identity & RBAC - Step-by-step guide to implementing core governance features
• Core Concepts - Understanding the SDK's architecture and pipeline
• Configuration - All available options and their usage
• Interfaces - Extensibility points and custom implementations
• Authorization - RBAC system and permission management
• Auditing & Logging - Observability and compliance features
• Default Implementations - Built-in components (development only)
• Security Considerations - Security best practices and warnings

---

The Problem: Production MCP Needs More

The standard @modelcontextprotocol/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) 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)
• ⚙️ 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)
• ☁️ Optional Managed Platform: Skip infrastructure setup and management by using the Ithena Managed Platform (join the waitlist!).

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)
• 📦 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.

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 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

You choose the approach that best fits your needs. The SDK seamlessly supports both self-hosted and platform-based backends.

Installation

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 for a runnable example.

Next Steps

• Understand the Core Concepts like GovernedServer and the pipeline.
• Review the Configuration Options available.
• Explore the Interfaces to integrate with your systems.
• Learn about Authorization and Auditing/Logging.
• Review the Security Considerations carefully.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on the GitHub repository.

License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.