McpServer resources

An McpServer is a Kubernetes resource that allows you to run the Apollo MCP Server, which exposes GraphQL operations against a graph as tools for AI agents.

When you create an McpServer in your cluster, the Apollo GraphOS Operator will automatically provision the following resources for you:

• A Deployment for the MCP Server

• A Service for traffic ingress

• A ConfigMap for your MCP Server configuration

• A Secret for an ephemeral graph API key, minted specifically for this McpServer

The McpServer resource also exposes the scale subresource, so PodDisruptionBudgets or HorizontalPodAutoscalers can connect to scale the fleet if necessary

Deploying an McpServer

To deploy an McpServer in your Kubernetes cluster, you must define the graph it should serve operations for, via spec.supergraphSource.

Here is an example that deploys an McpServer wired up to an existing Supergraph resource in the same cluster:

1apiVersion: apollographql.com/v1alpha1
2kind: McpServer
3metadata:
4  name: my-mcp-server
5spec:
6  replicas: 1
7  deployment:
8    podTemplate:
9      mcpServerVersion: "1.19.0"
10  supergraphSource:
11    supergraph:
12      name: my-supergraph
13      namespace: default

Specifying a schema source

The McpServer resource type needs the graph's whole schema, and the MCP Server has no ability to introspect it directly — so, unlike Supergraph, it doesn't support a bare GraphQL endpoint or inline SDL. It supports two schema sources instead:

• A Supergraph resource reference.

• A direct Apollo GraphOS Studio graph variant reference.

Supergraph resource reference

If you already have a Supergraph resource running in your cluster, reference it by name and namespace. The Operator resolves the live GraphQL endpoint from that Supergraph's own Service, and the graph ref from its schema source (this requires the referenced Supergraph to be sourced from Studio, a SupergraphSchema resource, or an OCI artifact with a graphRef set — a Supergraph using pure inline SDL has no graph ref and isn't supported here).

1spec:
2  supergraphSource:
3    supergraph:
4      name: my-supergraph
5      # Optional: if the resource is not in the same namespace as your McpServer,
6      # you can specify the namespace here:
7      namespace: default

Changes to the referenced Supergraph's schema don't cause the McpServer to redeploy: the MCP Server fetches its own schema directly from Apollo Uplink at runtime, so the Operator only needs the graph ref and live endpoint, neither of which change when the schema does.

Apollo GraphOS Studio

You can also point an McpServer directly at a Studio graph variant, without an in-cluster Supergraph.

1spec:
2  supergraphSource:
3    studio:
4      graphRef: my-graph@my-variant

By default, the Operator resolves the live GraphQL endpoint automatically, from the routing URL registered for that graph variant in Studio. If the variant has no registered routing URL, or you want to route operations somewhere else, set endpointOverride explicitly — this always takes precedence, and skips the Studio lookup entirely:

1spec:
2  supergraphSource:
3    studio:
4      graphRef: my-graph@my-variant
5      endpointOverride: https://my-router.example.com/graphql

Choosing how the MCP Server fetches its schema

By default, the MCP Server fetches its schema from Apollo Uplink. If your McpServer uses a Studio source, you can change this by setting schema.source in spec.config:

1spec:
2  config:
3    schema:
4      source: graphos

• uplink (default): fetch the schema from Apollo Uplink.

• graphos: fetch the latest published schema from the GraphOS Platform API. Use this for non-federated graphs, which Uplink can't serve.

• local: load the schema from a file. Set schema.path and make the file available to the container, using additionalVolumes and additionalVolumeMounts or a custom image.

For example, to load the schema from a ConfigMap named my-schema with a schema.graphql key:

1spec:
2  config:
3    schema:
4      source: local
5      path: /schema/schema.graphql
6  deployment:
7    podTemplate:
8      additionalVolumes:
9        - name: schema
10          configMap:
11            name: my-schema
12      mcpServerContainer:
13        additionalVolumeMounts:
14          - name: schema
15            mountPath: /schema

With a Studio source, the Operator can't tell whether Operator-managed routers also serve the same graph, so it doesn't restrict schema.source. If you do manage routers for this graph with the Operator, we recommend uplink: graphos can return a different schema from the one your routers serve, and local doesn't change when the graph does.

Configuring the MCP Server

Define MCP Server configuration directly in the McpServer CRD using the spec.config property, using the same structure as a standalone MCP Server configuration file.

For example, to enable the MCP Server's standard introspection-based tools:

1spec:
2  config:
3    introspection:
4      execute:
5        enabled: true
6      introspect:
7        enabled: true
8      search:
9        enabled: true
10      validate:
11        enabled: true

Operator-managed configuration keys

A handful of keys are required for the Operator to manage your deployment correctly, and are always overridden regardless of what you set:

• endpoint

• transport.type

• transport.address

• transport.port

• transport.stateful_mode

• health_check.enabled

• logging.path

• graphos