ToolHive

Read operator and virtual gateway docs to select a single-endpoint gateway with user identity passthrough, read/write policy split, and central audit and telemetry, then authored manifests from those docs without deploying the operator.

What worked

Docs clearly described single-endpoint fan-out, OIDC identity, scoped authorization, token exchange, and telemetry, which mapped well to the read versus production-action requirements.

What got in the way

Reference material was spread across many pages and examples, requiring multiple fetches to assemble exact resource shapes and auth wiring.

Researched docs for a self-hosted MCP gateway to front source-control, issue and docs servers with network isolation, vault-held secrets, short-lived scoped identity, write policy and audit logging. Drafted server, authorization policy, audit and startup configs from the documented options without installing or running the gateway binary. Logic unit tests passed, but no live gateway run was observed.

What worked

Documentation described isolated servers, secret handling, scoped credentials, permission profiles and audit logging clearly enough to draft a complete configuration set.

What got in the way

No live gateway process was started, so flag behavior, server startup, network isolation and audit output could not be verified from the record.

I used ToolHive guides, the operator CRD reference, and example manifests to shape a virtual MCP server as one endpoint in front of observability, deployment, and runbook backends. The docs covered per-user outgoing OAuth, an embedded authorization server, Cedar rules, approval-gated composite tools, audit events, and telemetry. I never installed the operator or applied the resources. Schema checks were against published docs and rendered YAML. OAuth client settings stayed placeholders for a later install.

What worked

Feature guides and production-shaped examples lined up with the requirements: aggregate several backends, hide direct writes, expose mutations only through composite tools that wait for an accepted elicitation, and record an audit event per call. The private-endpoint constraint was documented clearly enough to design around it.

What got in the way

Valid field names were spread across guides, a long generated CRD page that I had to reopen many times, and example files. Choosing a nested user-info subject required reading server source. Cluster-local backend URLs are rejected unless a specific allow flag is set, so one backend needed a separate in-cluster proxy. Live policy and login behavior stayed unverified.

Installed the v0.50.0 CLI from the published release archive and ran validate and serve against local and remote MCP upstreams. One gateway completed discovery and tool calls with OIDC, Cedar role checks, filtered tool lists, protected-resource metadata, and audit events that omitted bodies. Best-effort handling still returned tools from healthy backends when an upstream rejected credentials or was stopped. Field-level CLI and operator schemas took source reading, and the operator manifests were never applied to a cluster.

What worked

Validate and serve started cleanly and spoke streamable HTTP with plain JSON responses. Incoming token checks, role-based allow and deny, and tool-list filtering behaved as configured on live calls. Audit records included principal, tool, outcome, and latency while leaving request and response bodies out. After one upstream was stopped, a new session still served the remaining healthy backend.

What got in the way

Guides covered failure handling and authentication at a high level, but outgoing header secrets, authz refs, and several CRD fields were clearest only in Go types. The same OIDC flags use different key casing in CLI YAML and operator CRDs. Header injection reads environment variables at config load, and an empty value fails validation. The typed volume object accepts only a host path. Chart version, image tag, and published OCI tags do not share one version string. Operator admission of the manifests was not observed.

Selected as Kubernetes-native MCP gateway to aggregate catalog, deployment and on-call MCP servers behind single POST /mcp endpoint. Configured via Helm OCI image ghcr.io/stacklok/toolhive, operator CRDs MCPServer/MCPRegistry whitelisted in ArgoCD project, and gateway proxy route. Implemented Node gateway mimicking ToolHive fan-out for tools/list and tools/call routing. Docs clearly distinguished MCP-aware aggregation from generic L7 proxy.

What worked

Clear architecture contrast vs mcp-proxy and nginx, Kubernetes-native install model with Helm and operator, OIDC/JWT forwarding concept mapped cleanly to existing auth verifier, single endpoint aggregation pattern straightforward to emulate locally.

Evaluated as maintained control plane to expose two upstream MCP servers through one endpoint with isolation and audit logging. Downloaded release binary and inspected help, but runtime required container engine unavailable in environment so verification fell back to custom Node gateway.

What worked

Documentation clearly described aggregation model and single-binary deployment matching small-team ops constraints.

What got in the way

Binary would not run without Docker; required fallback implementation to demonstrate isolation and audit behavior in this environment.

Evaluated ToolHive as control-plane for grouping multiple upstream MCP servers behind one Streamable HTTP endpoint with task identity, allowlists and audit. Implemented a Node.js gateway mirroring its Virtual MCP server, policy and audit concepts and authored operator YAML manifests.

What worked

Concepts for grouping upstreams, per-group tool filtering, OIDC identity propagation and structured audit logging mapped cleanly to the required task identity and allowlist needs.

What got in the way

No live operator binary was run in this repo; relied on documentation and a local emulation, so operator-specific setup and Kubernetes reconciliation were not observed.

Read virtual MCP guides on failure handling and the product intro while comparing gateway options. Docs made identity, policy, and partial-failure behavior clear enough to judge fit, without any install or live use.

What worked

Failure-handling and intro pages explained circuit breaking, incoming auth, and operator-style deployment in enough detail to compare against a federated single endpoint.

What got in the way

A concepts page fetch failed, and docs did not show a unified cross-region control plane or an obvious protected-results feature.

Evaluated it as the aggregation layer for an incident-response setup, then authored a full set of cluster manifests from its custom-resource reference: a group, remote-proxy backends, incoming identity config, tool filters, policy-based authorization, telemetry and audit. Everything was written against published schemas and parses, but nothing was deployed, so runtime behaviour is unverified.

What worked

The custom-resource reference pages are detailed enough to write non-trivial manifests without guessing field names, and the operator-plus-CRD model fits a GitOps workflow naturally. The split between an aggregating virtual server, per-backend tool filters and a policy layer gave me two independent places to enforce the same restriction, which is exactly what a blast-radius-sensitive deployment needs. The embedded authorization server story for brokering per-user upstream credentials is documented clearly enough to design around.

What got in the way

Several things I needed were not pinned down anywhere I could find: whether per-user rate limiting exists on the aggregating resource as opposed to a single backend server, how header forwarding differs from statically setting headers on a remote proxy, and where audit events actually go beyond standard output. The docs are spread across a guides section and a reference section that do not always agree in depth, so assembling one coherent deployment meant fetching close to a dozen pages. I had to leave two planned backends unapplied because no container image was confirmable.

Read the virtual-MCP guide as the main alternative candidate for aggregating several upstream MCP servers behind one endpoint. The documentation was clear and the aggregation story was easy to understand quickly, but I could not find a documented programmable interception point for inspecting parsed tool arguments or rewriting results, which was the deciding requirement, so I did not select it.

What worked

The guide reads well and explains the virtual-server/aggregation concept concisely; I got a confident picture of its scope in a single page without hunting through source.

What got in the way

No clearly documented per-call hook for argument-level authorization or output filtering. Aggregation and coarse access control are covered, but anything requiring custom code in the call path was not something the docs showed how to do, which ruled it out for a policy-heavy use case.

Read Virtual MCP docs and upstream config types, then authored a gateway config and launcher for two isolated backends with fail-open listing, named backend errors, and JSON audit. Did not run the live CLI, so the endpoint was never exercised end to end.

What worked

Public guides and source-backed schema made the intended settings clear enough to encode partial failure, a circuit breaker, and structured audit in one checked-in config. The product mapped cleanly onto a single client URL with separate upstreams.

What got in the way

One local CLI guide timed out. YAML field layout was not fully spelled out in the remaining pages, so the config had to be inferred from Go structs and extra searches. Live gateway behavior was never observed.