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 initcreates the file, and--from-serverfills in tools from a running instance. Thenserver build,server push, andserver deploypublish 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.
- 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/v1alpha1types as the source of truth before production use.
Features
MCPServerandMCPAccessGrantare namespaced CRDs, so servers and grants are visible and reviewable withkubectl. Agent sessions are stored by the platform and synchronized to the gateway.- The
mcp-gatewaysidecar applies deny-by-default tool rules, trust ceilings, side-effect limits, session expiry, and revocation on everytools/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 proxygives 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
teamIDsubject 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-runtimeCLI forauth,bootstrap,setup,status,registry,server,catalog,cluster,access,team, andopsmcp-runtime adapter proxyfor governed Streamable HTTP agent integrations. It enrolls a session-bound client certificate with--server <name> --agent <id>once an enabled grant exists;--auto-refreshrenews the certificate (see Agent Adapter)- Platform UI for authenticated MCP catalog browsing, platform state, and web operations
MCPServerandMCPAccessGrantCRDs, 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 inmcp-observability. Promtail runs inmcp-log-collector. MCP servers stay inmcp-servers,mcp-servers-org,mcp-servers-public, ormcp-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
kubectlonPATH, configured for the target clustercurl,jq, andpython3for documented dev and traffic-generation flowskindfor 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.mdto choose the install shape, thendocs/cluster-readiness.mdbefore 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.
