Skip to content

Commit 54acf32

Browse files
kbychuDaleSeo
kbychu
authored and
DaleSeo
committed
Opinionated AIO use
1 parent 497633e commit 54acf32

File tree

1 file changed

+82
-26
lines changed

1 file changed

+82
-26
lines changed

‎docs/source/deploy.mdx‎

Lines changed: 82 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,61 @@
22
title: Deploy the MCP Server
33
---
44

5-
You can deploy and operate the MCP server by:
5+
## Recommended: Apollo Runtime Container (All-in-One)
66

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
7+
**For most production deployments, we recommend Apollo Runtime container.** It includes everything you need to serve both GraphQL and MCP requests in a single, optimized container.
98

10-
### Deploy the MCP Server container
9+
### Why choose the All-in-One container?
1110

12-
Apollo MCP Server is available as a standalone docker container. Container images are downloadable using
11+
- **Simplified operations**: Single container to deploy and manage
12+
- **Optimized performance**: Apollo Router and Apollo MCP Server are co-located
13+
- **Built-in best practices**: Pre-configured for production use
14+
- **Easier scaling**: Scale both GraphQL and MCP together
15+
- **Unified monitoring**: Single service to monitor and debug
16+
17+
### Deploy Apollo Runtime container
18+
19+
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.
20+
21+
```bash title="Deploy with GraphOS (Recommended)"
22+
docker run \
23+
-p 4000:4000 \
24+
-p 5000:5000 \
25+
--env APOLLO_GRAPH_REF="<your-graph-ref>" \
26+
--env APOLLO_KEY="<your-graph-api-key>" \
27+
--env MCP_ENABLE=1 \
28+
--rm \
29+
ghcr.io/apollographql/apollo-runtime:latest
30+
```
31+
32+
When you run this, it will:
33+
34+
- Fetch your schema from GraphOS
35+
- Configure Apollo Router with your supergraph
36+
- Enable Apollo MCP Server endpoint at `/mcp`
37+
- Provide access to your GraphOS persisted queries for MCP tool configuration
38+
39+
<Note>
40+
41+
You'll still need to configure which operations to expose as MCP tools. See [Define MCP Tools](/apollo-mcp-server/define-tools) for configuration options.
42+
43+
</Note>
44+
45+
To learn more, review the [Apollo Runtime container documentation](/graphos/routing/self-hosted/containerization/docker).
46+
47+
## Alternative: Standalone Apollo MCP Server container
48+
49+
**Use this option only 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
1354
the image `ghcr.io/apollographql/apollo-mcp-server`.
1455

1556
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.
57+
and that clients use Streamable HTTP transport on container port `5000`.
1758

18-
An example `docker run` command that runs the MCP Server for the space dev example:
59+
Here's an example `docker run` command that runs Apollo MCP Server for the space dev example:
1960

2061
```yaml title="Example config for using Docker"
2162
endpoint: https://thespacedevs-production.up.railway.app/
@@ -39,31 +80,46 @@ docker run \
3980
ghcr.io/apollographql/apollo-mcp-server:latest /config.yaml
4081
```
4182

42-
### Deploy the MCP Server using the Apollo Runtime container
83+
## When to choose which option?
4384

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.
85+
| Scenario | Recommended Option | Why |
86+
|----------|-------------------|-----|
87+
| **New GraphQL + MCP deployment** | **Apollo Runtime Container** | Single container, easier to manage, optimized performance |
88+
| **Adding MCP to existing GraphQL API** | Standalone Apollo MCP Server | Connect to your existing GraphQL endpoint |
89+
| **GraphOS managed graph** | **Apollo Runtime Container** | Automatic schema/PQ sync, unified telemetry |
90+
| **Local development** | Either option works | Choose what matches your production setup |
91+
| **Kubernetes/orchestrated environment** | **Apollo Runtime Container** | Fewer moving parts, simpler networking |
4592

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+
## Production Considerations
4794

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+
### Load Balancing & Session Affinity
5896

59-
To learn more, review the [Apollo Runtime container documentation](/graphos/routing/self-hosted/containerization/docker).
97+
**Important**: MCP is a stateful protocol that requires session affinity (sticky sessions).
98+
99+
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.
100+
101+
**Cloud Provider Support:**
102+
103+
- Most cloud load balancers (ALB, GCP LB) don't support header-based session affinity
104+
- Use Nginx, HAProxy, or Envoy/Istio for proper session routing
105+
106+
### Scaling Recommendations
107+
108+
**Apollo Runtime Container** (Recommended):
109+
110+
- Scale both GraphQL and MCP together as a single unit
111+
- Simpler horizontal scaling
112+
- Consistent performance characteristics
60113

61-
### Using a load balancer
114+
**Standalone Apollo MCP Server**:
62115

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_.
116+
- Scale Apollo MCP Server independently of your GraphQL API
117+
- More complex but enables fine-tuned resource allocation
64118

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.
119+
### Next steps
66120

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.
121+
After you deploy, configure:
68122

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.
123+
1. [Health checks](/apollo-mcp-server/health-checks) for monitoring
124+
2. [CORS settings](/apollo-mcp-server/cors) for browser clients
125+
3. [Authorization](/apollo-mcp-server/auth) for production security

0 commit comments

Comments
 (0)