MCPServerEntry

MCPServerEntry declares a remote MCP server as a first-class member of an MCPGroup without running a full MCPRemoteProxy. Entries appear in registry listings and participate in group-scoped aggregations like a VirtualMCPServer.

API: toolhive.stacklok.dev/v1alpha1 · Scope: Namespaced · Short names: mcpentry

Example

mcpserverentry.yaml

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPServerEntry
metadata:
  name: my-mcpserverentry
  namespace: default
spec:
  groupRef:
    name: <string>
  remoteUrl: <string>
  transport: sse

Schema

spec

MCPServerEntrySpec defines the desired state of MCPServerEntry. MCPServerEntry is a zero-infrastructure catalog entry that declares a remote MCP server endpoint. Unlike MCPRemoteProxy, it creates no pods, services, or deployments.

Field	Type	Description
caBundleRef	object	CABundleRef references a ConfigMap containing CA certificates for TLS verification when connecting to the remote MCP server.
externalAuthConfigRef	object	ExternalAuthConfigRef references a MCPExternalAuthConfig resource for token exchange when connecting to the remote MCP server. The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPServerEntry.
groupRefrequired	object	GroupRef references the MCPGroup this entry belongs to. Required — every MCPServerEntry must be part of a group for vMCP discovery.
headerForward	object	HeaderForward configures headers to inject into requests to the remote MCP server. Use this to add custom headers like API keys or correlation IDs.
remoteUrlrequired	string	RemoteURL is the URL of the remote MCP server. Both HTTP and HTTPS schemes are accepted at admission time. pattern ^https?://
transportrequired	string	Transport is the transport method for the remote server (sse or streamable-http). No default is set (unlike MCPRemoteProxy) because MCPServerEntry points at external servers the user doesn't control — requiring explicit transport avoids silent mismatches. enum: sse | streamable-http

spec.caBundleRef

CABundleRef references a ConfigMap containing CA certificates for TLS verification when connecting to the remote MCP server.

Field	Type	Description
configMapRef	object	ConfigMapRef references a ConfigMap containing the CA certificate bundle. If Key is not specified, it defaults to "ca.crt".

↑ Back to spec

spec.caBundleRef.configMapRef

ConfigMapRef references a ConfigMap containing the CA certificate bundle. If Key is not specified, it defaults to "ca.crt".

Field	Type	Description
keyrequired	string	The key to select.
name	string	Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names default ""
optional	boolean	Specify whether the ConfigMap or its key must be defined

↑ Back to spec.caBundleRef

spec.externalAuthConfigRef

ExternalAuthConfigRef references a MCPExternalAuthConfig resource for token exchange when connecting to the remote MCP server. The referenced MCPExternalAuthConfig must exist in the same namespace as this MCPServerEntry.

Field	Type	Description
namerequired	string	Name is the name of the MCPExternalAuthConfig resource

↑ Back to spec

spec.groupRef

GroupRef references the MCPGroup this entry belongs to. Required — every MCPServerEntry must be part of a group for vMCP discovery.

Field	Type	Description
namerequired	string	Name is the name of the MCPGroup resource in the same namespace minLength 1

↑ Back to spec

spec.headerForward

HeaderForward configures headers to inject into requests to the remote MCP server. Use this to add custom headers like API keys or correlation IDs.

Field	Type	Description
addHeadersFromSecret	object[]	AddHeadersFromSecret references Kubernetes Secrets for sensitive header values.
addPlaintextHeaders	map<string, string>	AddPlaintextHeaders is a map of header names to literal values to inject into requests. WARNING: Values are stored in plaintext and visible via kubectl commands. Use addHeadersFromSecret for sensitive data like API keys or tokens.

↑ Back to spec

spec.headerForward.addHeadersFromSecret[]

AddHeadersFromSecret references Kubernetes Secrets for sensitive header values.

Field	Type	Description
headerNamerequired	string	HeaderName is the HTTP header name (e.g., "X-API-Key") minLength 1 · maxLength 255
valueSecretRefrequired	object	ValueSecretRef references the Secret and key containing the header value

↑ Back to spec.headerForward

spec.headerForward.addHeadersFromSecret.valueSecretRef

ValueSecretRef references the Secret and key containing the header value

Field	Type	Description
keyrequired	string	Key is the key within the secret
namerequired	string	Name is the name of the secret

↑ Back to spec.headerForward.addHeadersFromSecret

status

MCPServerEntryStatus defines the observed state of MCPServerEntry.

Field	Type	Description
conditions	object[]	Conditions represent the latest available observations of the MCPServerEntry's state.
observedGeneration	integer	ObservedGeneration reflects the generation most recently observed by the controller. format int64
phase	string	Phase indicates the current lifecycle phase of the MCPServerEntry. default "Pending" · enum: Valid | Pending | Failed

status.conditions[]

Conditions represent the latest available observations of the MCPServerEntry's state.

Field	Type	Description
lastTransitionTimerequired	string	lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. format date-time
messagerequired	string	message is a human readable message indicating details about the transition. This may be an empty string. maxLength 32768
observedGeneration	integer	observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. format int64 · min 0
reasonrequired	string	reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. pattern ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ · minLength 1 · maxLength 1024
statusrequired	string	status of the condition, one of True, False, Unknown. enum: True | False | Unknown
typerequired	string	type of condition in CamelCase or in foo.example.com/CamelCase. pattern ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ · maxLength 316

↑ Back to status

Related resources

References:

• MCPExternalAuthConfig - via spec.externalAuthConfigRef
• MCPGroup - via spec.groupRef