MCP Runtime

MCP Runtime

MCP Runtime is a Kubernetes control plane for Model Context Protocol servers. It deploys MCP servers into your cluster, enforces per-tool access policy on every call, and records each decision for audit.

The workflow has three steps:

1. Describe your server in .mcp/servers.yaml: each tool's name, the trust level it requires, and its side effect. mcp-runtime server init creates the file, and --from-server fills in tools from a running instance. Then server build, server push, and server deploy publish it.
2. Grant access. An access grant (mcp-runtime access grant init) lets a person, agent, or team call specific tools on that server, up to a maximum trust level and only with the side effects you allow.
3. Open a session. An agent session (mcp-runtime access session init) time-boxes that access for one agent, and you can revoke it at any time.

On every call, a gateway in front of the server checks the caller's identity, session, trust level, and the tool's side effect before the call reaches your code, and records the decision for audit. MCPServer and MCPAccessGrant are cluster resources, and the operator creates the Deployment, Service, Ingress, and policy for you. Agent sessions are platform records in Postgres: create and revoke them with the CLI or UI. MCPAgentSession YAML is only an admin apply input, and Kubernetes session objects do not authorize calls.

A public preview runs at platform.mcpruntime.org. The same stack installs into your own cluster with mcp-runtime setup.

• Website · Docs (docs/) · API reference · Articles
• Running or evaluating an internal MCP platform? Open a GitHub issue with your use case, cluster shape, or integration feedback.

[!CAUTION] MCP Runtime is alpha software. APIs, commands, and behavior are still evolving. Use the docs, CRDs, and api/v1alpha1 types as the source of truth before production use.

Features

• MCPServer and MCPAccessGrant are namespaced CRDs, so servers and grants are visible and reviewable with kubectl. Agent sessions are stored by the platform and synchronized to the gateway.
• The mcp-gateway sidecar applies deny-by-default tool rules, trust ceilings, side-effect limits, session expiry, and revocation on every tools/call.
• Every allow and deny decision is recorded with the identity, tool, reason, and policy version, and is queryable through the platform API and dashboards.
• adapter proxy gives IDEs, agent frameworks, and scripts a local Streamable HTTP endpoint that adds a session-bound client certificate with automatic refresh and forwards OAuth when the target requires it.
• Team namespaces, RBAC, and teamID subject matching let several teams publish and govern servers on one cluster, with private, org-wide, or public catalogs.
• Setup, registry and image-pull wiring, ingress, rollout readiness, cluster doctor, cluster diagnostics, and status commands are included.
• Documented install paths cover Kind, k3s, self-managed clusters, and managed Kubernetes with external registries.

What ships

• mcp-runtime CLI for auth, bootstrap, setup, status, registry, server, catalog, cluster, access, team, and ops
• mcp-runtime adapter proxy for governed Streamable HTTP agent integrations. It enrolls a session-bound client certificate with --server <name> --agent <id> once an enabled grant exists; --auto-refresh renews the certificate (see Agent Adapter)
• Platform UI for authenticated MCP catalog browsing, platform state, and web operations
• MCPServer and MCPAccessGrant CRDs, plus platform-stored agent sessions
• Kubernetes operator for Deployment, Service, Ingress, and policy materialization
• Internal or provisioned registry workflows
• Optional gateway enforcement for identity, tool policy, trust, and audit emission
• Bundled platform stack for ingest, processing, API, UI, and observability. Control-plane services run in mcp-platform. The event pipeline and telemetry stack run in mcp-observability. Promtail runs in mcp-log-collector. MCP servers stay in mcp-servers, mcp-servers-org, mcp-servers-public, or mcp-team-{slug}. See Namespaces.

Requirements

Using the hosted platform requires the CLI; release installation needs curl or wget on macOS/Linux, or PowerShell on Windows.

For self-hosting and source/contributor workflows, host tools include:

• Go 1.26+ and Make for source builds and contributor workflows (release CLI installs do not need them)
• Docker or a Docker-compatible client, with the daemon running
• kubectl on PATH, configured for the target cluster
• curl, jq, and python3 for documented dev and traffic-generation flows
• kind for local Kind-based clusters

Cluster prerequisites:

• A running Kubernetes cluster: kind, k3s, minikube, Docker Desktop Kubernetes, EKS, GKE, AKS, or equivalent
• Working DNS, default storage class, ingress, and load-balancing path for your distribution
• See docs/deployment-targets.md to choose the install shape, then docs/cluster-readiness.md before running production-like installs

mcp-runtime setup installs the platform stack, including platform services such as ClickHouse and Kafka. You do not install those separately for the default flow.

Quick start

Install the CLI on macOS or Linux (the installer detects your OS and CPU):

curl -fsSL https://raw.githubusercontent.com/mcp-runtime/mcp-runtime/main/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
mcp-runtime --version

On macOS 13 or later, add --with-desktop to install the CLI and the Adapter desktop preview together (Apple Silicon and Intel):

curl -fsSL https://raw.githubusercontent.com/mcp-runtime/mcp-runtime/main/install.sh | sh -s -- --with-desktop

The app installs to ~/Applications/MCPRuntimeAdapter.app without sudo. It is an unsigned preview; macOS may require allowing it in System Settings → Privacy & Security. Open it and choose Install and start. The installer verifies release checksums and preserves any existing app. See the macOS adapter guide for setup and updates. Set MCP_RUNTIME_APP_DIR to choose another app directory.

For Windows, installation options, and your first hosted deployment, follow the Quickstart. No Kubernetes cluster is needed to use the hosted platform.

To install the platform on your own cluster, follow Getting Started. Choose a deployment target and check cluster readiness before setup.

To build from source or run a disposable local Kind cluster, start with the Contributor Guide.

Common commands

./bin/mcp-runtime bootstrap              # preflight cluster prerequisites
./bin/mcp-runtime setup                  # install platform stack
./bin/mcp-runtime status                 # show platform health
./bin/mcp-runtime auth login --api-url <platform-url>   # save platform credentials
./bin/mcp-runtime team create acme --name "Acme Corp"   # create a team namespace (admin)
./bin/mcp-runtime registry status        # inspect registry
./bin/mcp-runtime server status          # inspect MCP servers
./bin/mcp-runtime catalog tools          # search tools across visible servers
./bin/mcp-runtime access grant list      # inspect access grants
./bin/mcp-runtime adapter proxy --server <name> --agent <id> --auto-refresh   # connect an MCP client
./bin/mcp-runtime ops status        # inspect platform stack

Comparison

Features and deployment models change; check each project's current documentation before choosing.

MCP directories and catalogs

The Official MCP Registry, Glama, Smithery, Docker MCP Catalog, PulseMCP, mcp.so, and client-specific catalogs help people find and install public MCP servers. MCP Runtime runs MCP servers inside your own cluster and governs calls to them. The two are complementary: a server you find in a directory can be deployed and governed with MCP Runtime.

MCP gateways and platforms

Several projects run MCP servers on Kubernetes or define Kubernetes APIs for MCP traffic. MCP Runtime's focus is expressing server workloads and access policy (trust ceilings, allowed side effects, per-tool rules, user consent, expiry, revocation) as validated Kubernetes resources that the operator reconciles and the gateway enforces.

When to choose MCP Runtime

Choose MCP Runtime when you want one system to deploy MCP servers into your cluster and enforce who may call which tool, with what trust and consent.

Another project may fit better if your main need is broad SaaS integrations, model routing and spend controls, API-to-MCP conversion, remote zero-trust networking, or a full agent/chat product.

Development checks

gofmt -s -l .
go build -o bin/mcp-runtime ./cmd/mcp-runtime
go test ./... -count=1 -race
go vet ./...

For targeted tests, e2e setup, and debugging runbooks, use AGENTS.md and the docs site.

Agent tool configuration

The repo keeps Claude-specific local configuration in .claude/. Its skills entry is expected to be a symlink to ../.codex/skills, so Claude Desktop and the Codex CLI discover the same repository skills during local development.

License

Apache License 2.0. See LICENSE.