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:
- 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.
- 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.
- 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.
[!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 opsmcp-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 clustercurl, jq, and python3 for documented dev and traffic-generation flowskind 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.
| Directories and catalogs | MCP Runtime |
|---|
| Purpose | Find and install public servers | Host, deploy, govern, and audit your own servers |
| Data | Discovery metadata, popularity, install snippets | MCPServer resources, grants, sessions, policy decisions, audit events |
| Where it runs | Third-party hosted service or client feature | Your Kubernetes cluster |
| Request path | Ends once the client is configured | Every tool call passes through the gateway |
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.
| Project | Focus | Compared with MCP Runtime |
|---|
| Archestra | MCP platform with Kubernetes server orchestration, gateway, registry, and agent/chat features | Overlaps on Kubernetes-hosted servers; broader agent platform. MCP Runtime centers access on grant and session resources. |
| Obot | MCP hosting, registry, gateway, and an organization-facing AI experience | Also hosts MCP servers. MCP Runtime keeps workload and access policy as Kubernetes state. |
| Microsoft MCP Gateway | Kubernetes-oriented MCP gateway and management APIs, adapter/tool lifecycle, identity integrations | Overlaps on Kubernetes. MCP Runtime models deployment, grants, and consented sessions as resources. |
| Agent Router | Kubernetes Gateway API routing for MCP and AI traffic | Overlaps on Kubernetes APIs, focused on routing. MCP Runtime also manages server workloads and session consent. |
| agentgateway | High-performance data-plane gateway for MCP, agents, and AI traffic | Focused on routing and policy in the data plane. MCP Runtime owns workload lifecycle and access state. |
| IBM ContextForge | Federation and gateway for MCP, A2A, REST, and gRPC | Broader protocol federation. MCP Runtime focuses on Kubernetes workload and access governance. |
| MCPJungle | Self-hosted team gateway, unified endpoint, discovery, tool grouping | Centers aggregation. MCP Runtime ties access decisions to reconciled cluster resources. |
| Unla |
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.
