peta-core

# Peta Core A control-plane runtime for MCP (Model Context Protocol). Gateway, vault, policy engine, and audit trail for every tool call between AI agents and downstream MCP servers. Supports the core infrastructure components required to run MCP in production: gateway routing, runtime supervision, policy enforcement, credential management, and audit logging.     **Key guarantees:** - **Credential vault.** Secrets stay encrypted at rest (PBKDF2 + AES-GCM) and are injected server-side at execution time. Clients never see raw credentials. - **Policy engine.** RBAC/ABAC with per-user, per-tool capability filtering. Optional human-in-the-loop approval for high-risk operations. - **Audit trail.** Every tool call is logged with caller identity, policy decision, and outcome. Secrets are never included in logs. - **Managed runtime.** Supervises downstream MCP servers with lifecycle controls and automated recovery. - **Protocol compatibility.** Standard MCP upstream and downstream. Existing clients and servers work without modification or custom extensions. - **Self-hosted.** On-premises deployment model. No hosted SaaS dependency. [Quick Start](https://peta.io/quick-start) | [Website](https://peta.io) | [Documentation](https://docs.peta.io) --- ## Architecture  Peta Core sits between MCP clients (Claude, ChatGPT, Cursor, n8n, or any MCP-compatible client) and downstream MCP servers. From the client's perspective, it connects to a single MCP server. Behind that endpoint, Peta Core routes to multiple downstream servers using standard MCP in both directions. Peta Core is one component of the Peta MCP stack: - **Peta Core** (this repository) — MCP gateway, credential vault, policy engine, and audit runtime. - **Peta Console** — Admin UI for users, servers, policies, approvals, and audit logs. - **Peta Desk** — Desktop client for approval workflows and per-user server configuration. > This repository contains only Peta Core. See [docs.peta.io](https://docs.peta.io) for the full stack. --- ## Features ### MCP Gateway - Transparent MCP proxying. Acts as an MCP server upstream and an MCP client downstream. Routes tool calls via namespaced identifiers (`serverId::toolName`). - Built-in OAuth 2.0 authorization server. Authorization Code with PKCE, refresh tokens, dynamic client registration, token introspection, and revocation. - Anonymous public access mode. Optionally allow token-less access for selected public servers through `/mcp/public`, while authenticated traffic continues on the standard `/mcp` endpoint, with configurable anonymous rate limits. ### Runtime & Extensions - Downstream server runtime. Lazy start on first request, health checks, idle timeouts, and capability caching. - Custom MCP tools (HTTPS or stdio). HTTPS-based custom tools remain supported, with stdio transport added for process-based tools. - Docker-safe `CustomStdio` execution. In Docker deployments, non-`docker` stdio commands are transparently executed inside `petaio/mcp-runner:latest`; explicit `docker` commands keep their original behavior. - REST API adapter. Register HTTP endpoints as MCP servers. Peta Core translates tool calls to HTTP requests without writing a custom MCP server. - Skill packages. Upload per-server ZIP bundles with `SKILL.md` metadata. Served as namespaced MCP tools, isolated by server ID. ### Credential Vault - Server-side credential injection. Credentials are decrypted and injected at execution time. They never appear in client configs or prompts. - Encrypted configuration storage. Server launch configs and per-user configuration blobs are encrypted at rest. - OAuth token brokerage. Stores downstream OAuth configurations encrypted, refreshes access tokens automatically, and injects them into downstream calls. Refresh tokens are never exposed. ### Policy Engine - Per-user, per-tool policy evaluation. RBAC/ABAC rules with content-aware DSL conditions and capability filtering. - Human-in-the-loop approvals. Durable approval queue with explicit lifecycle states and replay-safe retries. - Rate limiting and network controls. Per-user quotas with sliding window enforcement. Optional IP allow-lists per workspace. ### Result Cache - Configurable result caching with per-entity policy controls (`tools`, `prompts`, `resources.inline`, `resources.exact`, `resources.patterns`). - Safe-by-default behavior for tool results: approval-gated or error results are not promoted into cache. - Scope-aware cache keys and purge controls, including exact purge with operation/entity-level targeting. ### Progressive Disclosure - Configurable tool visibility. Three discovery modes (`FLAT`, `HYBRID`, `STRICT`) control whether tools are directly exposed or discoverable only through a catalog search interface. - Discovery profiles. Named profiles with rule-based exposure policies determine which tools are directly callable based on server identity and risk level. - Persistent catalog index. A searchable index of all tool capabilities across managed servers, with native `catalog.search`, `catalog.describe`, and `catalog.execute` tools for AI-driven discovery. ### Audit & Observability - Audit trail. Records caller identity, tool name, policy decision, approval status, and outcome for every tool call. Secrets are excluded from log payloads. - Structured logging. Pino-based JSON logs with per-module child loggers. Integrates with external log aggregation via webhook. - Observability workflows. Audit records and structured logs support log views, export workflows, and usage dashboards. ### Reliability - Stream resumption. Events are persisted to allow clients to resume via `Last-Event-ID` after disconnection. - Real-time notification channel. Socket.IO-based push for approval requests, capability updates, and server status changes. - Automatic server recovery. Consecutive downstream timeouts trigger a health ping and automatic reconnection. - Request-level retry. On downstream disconnection, the gateway reconnects and retries the call up to two times. Clients see a single request. --- ## Documentation - [Architecture & Internals](./docs/architecture.md) — System architecture, request flows, and core design patterns. - [Security & Permissions](./docs/security.md) — Vault encryption model and the three-layer permission system. - [Deployment & Configuration](./docs/deployment.md) — Docker, PM2 deployment, and environment variables. - [Reference](./docs/reference.md) — API surfaces, usage examples, and contributing. --- ## License Licensed under the [Elastic License 2.0 (ELv2)](./LICENSE). You may use, modify, and self-host this software. You may not provide it to third parties as a hosted or managed service, remove license key functionality, or obscure licensing notices. For detailed terms, see the [LICENSE](./LICENSE) file. Copyright © 2026 [Dunia Labs, Inc.](https://dunialabs.io)