Setting the file. One moment.
Subchapter 6.3
references/troubleshooting.mdMarkdown5 KBView on GitHub
MCP Inspector provides visual debugging for MCP servers.
npx @modelcontextprotocol/inspector# Start inspector with your MCP server using the Streamable HTTP transport
npx @modelcontextprotocol/inspector --transport http --server-url http://localhost:8000/mcp# Start inspector with your MCP server using the STDIO transport
npx @modelcontextprotocol/inspector apollo-mcp-server ./config.yamlSymptoms: Server exits immediately or hangs
Solutions:
# Validate YAML
npx yaml-lint config.yamlAPOLLO_MCP_LOGGING__LEVEL=debug apollo-mcp-server ./config.yamlSymptoms: MCP client shows “server not found” or timeout
Solutions:
Streamable HTTP (recommended for remote/multi-client):
Configure your client to connect via npx mcp-remote:
{
"mcpServers": {
"graphql": {
"command": "npx",
"args": ["mcp-remote", "http://127.0.0.1:8000/mcp"]
}
}
}Stdio (client launches the server process):
{
"mcpServers": {
"graphql": {
"command": "./apollo-mcp-server",
"args": ["/absolute/path/to/config.yaml"]
}
}
}Test server manually:
apollo-mcp-server ./config.yaml
# Should output JSON-RPC initializationCheck binary is installed:
which apollo-mcp-serverSymptoms: All requests return 401
Solutions:
echo $API_TOKEN # Should not be emptyheaders:
Authorization: "Bearer ${env.API_TOKEN}"forward_headers:
- x-forwarded-authorizationFor streamable_http transport, use transport.auth for OAuth:
transport:
type: streamable_http
auth:
servers:
- https://auth.example.com/.well-known/openid-configuration
audiences:
- https://api.example.com
scopes:
- readFor forwarding user tokens to the upstream GraphQL API:
forward_headers:
- authorizationSecurity Warning: Forwarding OAuth tokens exposes them to the MCP server. Ensure:
Symptoms: “Schema file not found” error
Solutions:
schema:
source: local
path: /absolute/path/to/schema.graphqlls -la ./schema.graphqlSymptoms: “Failed to fetch schema from uplink”
Solutions:
echo $APOLLO_KEY
echo $APOLLO_GRAPH_REFgraphos:
apollo_graph_ref: my-graph@production # Format: graph@variantSymptoms: “Field X not found on type Y”
Solutions:
validate tool before execute:validate(operation: "query { user { id name } }")Symptoms: “Mutations are disabled”
Solutions:
Check mutation mode in config:
overrides:
mutation_mode: all # Or 'explicit' for confirmationSymptoms: “Variable $id expected ID!, got String”
Solutions:
Ensure variable types match operation:
# Operation expects ID!
query GetUser($id: ID!) { ... }
# Correct invocation
execute(variables: { id: "123" }) # String coerced to IDFor streamable_http transport, health endpoints help diagnose issues.
| Endpoint | Purpose |
|---|---|
/health | Overall health status |
/health?live | Liveness probe (is server running?) |
/health?ready | Readiness probe (can server handle requests?) |
| Code | Meaning |
|---|---|
| 200 | Healthy |
| 503 | Unhealthy |
curl http://localhost:8000/health
# {"status": "UP"}
curl http://localhost:8000/health?ready
# {"status": "UP"}Schema check failing:
Endpoint check failing:
If issues persist:
APOLLO_MCP_LOGGING__LEVEL=debug apollo-mcp-server ./config.yamlCheck Apollo documentation: https://apollographql.com/docs (opens in a new tab)
Report issues: https://github.com/apollographql/apollo-mcp-server/issues (opens in a new tab)