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

Architecture

Peta MCP Stack Overview

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

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 — System architecture, request flows, and core design patterns.
Security & Permissions — Vault encryption model and the three-layer permission system.
Deployment & Configuration — Docker, PM2 deployment, and environment variables.
Reference — API surfaces, usage examples, and contributing.

License

Licensed under the Elastic License 2.0 (ELv2).

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

peta-core