You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
subtitle: Deployment using Docker containers, when to choose which option, and production considerations
3
4
---
4
5
5
-
You can deploy and operate the MCP server by:
6
+
To deploy Apollo MCP Server in your production environment, use the recommended [Apollo Runtime Container](#apollo-runtime-container-recommended). You can also use a [standalone Apollo MCP Server container](#standalone-apollo-mcp-server-container) if needed.
6
7
7
-
- Using the [MCP server container](#deploying-the-mcp-server-container) or binary, which connects to an existing GraphQL API endpoint
8
-
- Using the [Apollo Runtime container](#deploying-mcp-using-the-apollo-runtime-container), which includes both an MCP server as well as the Apollo router
8
+
## Apollo Runtime Container (Recommended)
9
9
10
-
### Deploy the MCP Server container
10
+
For most production deployments, use the all-in-one [Apollo Runtime Container](/graphos/routing/self-hosted/containerization/docker). It includes everything you need to serve both GraphQL and MCP requests in a single, optimized container.
11
11
12
-
Apollo MCP Server is available as a standalone docker container. Container images are downloadable using
13
-
the image `ghcr.io/apollographql/apollo-mcp-server`.
12
+
### Why choose the Apollo Runtime Container?
14
13
15
-
By default, the container expects all schema and operation files to be present in the `/data` folder within the container
16
-
and that clients will use the Streamable HTTP transport on container port 5000.
14
+
-**Simplified operations**: Single container to deploy and manage
15
+
-**Optimized performance**: Apollo Router and Apollo MCP Server are co-located
16
+
-**Built-in best practices**: Pre-configured for production use
17
+
-**Easier scaling**: Scale both GraphQL and MCP together
18
+
-**Unified monitoring**: Single service to monitor and debug
17
19
18
-
An example `docker run` command that runs the MCP Server for the space dev example:
20
+
### Deploy the Apollo Runtime Container
19
21
20
-
```yaml title="Example config for using Docker"
22
+
The Apollo Runtime Container includes all services necessary to serve GraphQL and MCP requests, including Apollo Router and Apollo MCP Server. Both port `4000` (GraphQL) and `5000` (MCP) are exposed.
23
+
24
+
```bash title="Deploy with GraphOS (Recommended)"
25
+
docker run \
26
+
-p 4000:4000 \
27
+
-p 5050:5000 \
28
+
--env APOLLO_GRAPH_REF="<your-graph-ref>" \
29
+
--env APOLLO_KEY="<your-graph-api-key>" \
30
+
--env MCP_ENABLE=1 \
31
+
-m /path/to/config:/config/mcp_config.yaml \
32
+
--rm \
33
+
ghcr.io/apollographql/apollo-runtime:latest
34
+
```
35
+
36
+
When you run this, it will:
37
+
38
+
- Fetch your schema from GraphOS using your graph credentials (`APOLLO_GRAPH_REF` and `APOLLO_KEY`)
39
+
- Start the Apollo Router with your graph configuration
40
+
- Provides a configuration file for the MCP server by mounting it to `config/mcp_config.yaml`
41
+
- Enable the Apollo MCP Server endpoint at `/mcp`
42
+
43
+
This command uses GraphOS-managed persisted queries for MCP tools. You'll need to publish your operations to the [GraphOS-managed persisted queries list](/apollo-mcp-server/define-tools#from-graphos-managed-persisted-queries). If you want to use other methods for defining MCP tools, see the [Define MCP Tools](/apollo-mcp-server/define-tools) page.
44
+
45
+
To learn more, see the [Apollo Runtime Container documentation](/graphos/routing/self-hosted/containerization/docker).
46
+
47
+
## Standalone Apollo MCP Server container
48
+
49
+
Use the standalone Apollo MCP Server container if you already have a GraphQL API running elsewhere and want to add MCP capabilities to it.
50
+
51
+
### Deploy standalone Apollo MCP Server container
52
+
53
+
Apollo MCP Server is available as a standalone Docker container. Container images are downloadable using the image `ghcr.io/apollographql/apollo-mcp-server`.
54
+
55
+
By default, the container expects all schema and operation files to be present in the `/data` directory within the container and that clients use Streamable HTTP transport on container port `5050`.
56
+
57
+
Here's an example `docker run` command that runs Apollo MCP Server for an example using [TheSpaceDevs graph](https://thespacedevs-production.up.railway.app/):
### Deploy the MCP Server using the Apollo Runtime container
81
+
##When to choose which option?
43
82
44
-
The Apollo Runtime container includes all services necessary to serve GraphQL and MCP requests, including the Router and MCP Server. It is the easiest way to operate a GraphQL API with MCP support.
| Adding MCP to existing GraphQL API | Standalone Apollo MCP Server | Connect to your existing GraphQL endpoint |
89
+
| Local development |`rover dev`|[Run `rover dev`](/apollo-mcp-server/run#with-the-rover-cli) to develop locally with both GraphQL and MCP |
90
+
91
+
## Production Considerations
45
92
46
-
To serve both MCP and GraphQL requests, both port `4000` and `5000` will need to be exposed. An example command which retrieves the schema from Uplink is:
93
+
### Load Balancing & Session Affinity
47
94
48
-
```bash title="Docker" {3, 6}
49
-
docker run \
50
-
-p 4000:4000 \
51
-
-p 5000:5000 \
52
-
--env APOLLO_GRAPH_REF="<your-graph-ref>" \
53
-
--env APOLLO_KEY="<your-graph-api-key>" \
54
-
--env MCP_ENABLE=1 \
55
-
--rm \
56
-
ghcr.io/apollographql/apollo-runtime:latest
57
-
```
95
+
MCP is a stateful protocol that requires session affinity (sticky sessions).
96
+
97
+
When an MCP client initializes a session with Apollo MCP Server, it receives a session identifier unique to that server instance through the `mcp-session-id` header. You must enable session affinity in your load balancer so that all requests sharing the same `mcp-session-id` are routed to the same backend instance.
98
+
99
+
Most cloud load balancers (ALB, GCP LB) don't support header-based session affinity. Use Nginx, HAProxy, or Envoy/Istio for proper session routing.
100
+
101
+
### Scaling Recommendations
102
+
103
+
For the Apollo Runtime Container:
58
104
59
-
To learn more, review the [Apollo Runtime container documentation](/graphos/routing/self-hosted/containerization/docker).
105
+
- Scale both GraphQL and MCP together as a single unit
106
+
- Simpler horizontal scaling
107
+
- Consistent performance characteristics
60
108
61
-
### Using a load balancer
109
+
For the standalone Apollo MCP Server container:
62
110
63
-
Because [MCP is a stateful protocol](https://modelcontextprotocol.io/docs/learn/architecture#lifecycle-management), you need to configure your load balancer to keep each session on the _same server instance_.
111
+
- Scale Apollo MCP Server independently of your GraphQL API
112
+
- More complex but enables fine-tuned resource allocation
64
113
65
-
When the MCP client initializes a session with Apollo MCP Server, it receives a session identifier unique to that server instance through the `mcp-session-id` header. You must enable session affinity ("sticky sessions") in your load balancer so that all requests that share the same `mcp-session-id` are routed to the same backend instance.
114
+
### Next steps
66
115
67
-
If the load balancer routes subsequent requests to a different instance, Apollo MCP Server rejects the request because it doesn't recognize the session id.
116
+
After you deploy, configure:
68
117
69
-
Many load balancers offered by major cloud vendors don't support header-based session affinity. If yours does not, use software such as Nginx, HAProxy, or Envoy/Istio in front of the Apollo MCP Server instances.
118
+
1.[Health checks](/apollo-mcp-server/health-checks) for monitoring
119
+
2.[CORS settings](/apollo-mcp-server/cors) for browser clients
120
+
3.[Authorization](/apollo-mcp-server/auth) for production security
0 commit comments