Galley MCP Server

Integrates Galley's GraphQL API with MCP clients. It automatically introspects the GraphQL schema for seamless use with tools like Claude and VS Code.

A Model Context Protocol (MCP) server for Galley GraphQL API integration using Apollo MCP Server withmandatory automatic schema introspection. The server introspects your Galley GraphQL schema on startup and provides seamless integration with MCP clients like Claude, Cursor, and VS Code.

- Docker installed on your system
- Galley API authentication (X-API-KEY or Bearer token)
- Network access to Galley GraphQL endpoints

# Option 1: Use pre-built image from public ECR (recommended) docker run -i -e X_API_KEY="your_api_key_here" public.ecr.aws/o0r1r5q2/galley-mcp:latest # Option 2: Build from source # Clone the repository git clone <your-repo-url> cd galley-mcp # Build the Docker image docker build -t galley-mcp . # Run with X-API-KEY authentication docker run -i -e X_API_KEY="your_api_key_here" galley-mcp # Or run with x-user-api-key authentication docker run -i -e X_USER_API_KEY="your_user_api_key_here" galley-mcp # Or run with Bearer token authentication docker run -i -e GALLEY_AUTH_TOKEN="your_bearer_token_here" galley-mcp

Pre-built multi-architecture Docker images are available from Amazon ECR Public Gallery:

- Registry:public.ecr.aws/o0r1r5q2/galley-mcp
- Latest:public.ecr.aws/o0r1r5q2/galley-mcp:latest
- Architectures:linux/amd64,linux/arm64
- Automatic releases: Images are automatically built and published on every commit to master branch

- latest- Latest stable version from master branch
- v1.0.0,v1.1.0, etc. - Semantic version tags from releases
- 1.0.0,1.1.0, etc. - Version tags without 'v' prefix
- develop- Latest development version from develop branch
- Schema Introspection: Automatically introspects the Galley GraphQL schema fromhttps://app.galleysolutions.com/graphql
- Schema Validation: Verifies the schema was successfully retrieved (startup fails if introspection fails)
- MCP Server Start: Launches Apollo MCP Server with the introspected schema and your operations

MCP servers need to run ininteractive mode(-iflag) to communicate with MCP clients. This allows:

- Bidirectional communicationbetween the client and server
- Real-time request/response handlingfor GraphQL operations
- Proper stdin/stdout stream managementfor MCP protocol

Always usedocker run -iwhen running the container for MCP client integration.

# Update package index sudo apt-get update # Install required packages sudo apt-get install ca-certificates curl gnupg lsb-release # Add Docker's official GPG key sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # Add Docker repository echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # Install Docker Engine sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin # Add your user to docker group (optional, to run without sudo) sudo usermod -aG docker $USER newgrp docker # Verify installation docker --version

- Download Docker Desktop fromhttps://www.docker.com/products/docker-desktop
- Install the.dmgfile
- Launch Docker Desktop from Applications
- Verify installation:docker --version

# Install Homebrew if not already installed /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Install Docker brew install --cask docker # Launch Docker Desktop open /Applications/Docker.app # Verify installation docker --version

- Download Docker Desktop fromhttps://www.docker.com/products/docker-desktop
- Run the installer
- Restart your computer when prompted
- Launch Docker Desktop
- Verify installation:docker --version

# Enable WSL2 wsl --install # Install Docker in WSL2 # Follow Linux installation steps inside WSL2

# Uses production endpoints by default docker run -i -e X_API_KEY="your_key" public.ecr.aws/o0r1r5q2/galley-mcp:latest

# Enable staging mode docker run -i -e X_API_KEY="your_key" -e STAGING=true public.ecr.aws/o0r1r5q2/galley-mcp:latest

# Override specific endpoints (takes precedence over STAGING flag) docker run -i \ -e X_API_KEY="your_key" \ -e ENDPOINT="https://custom.galleysolutions.com/graphql" \ -e INTROSPECT_ENDPOINT="https://custom-introspect.galleysolutions.com/graphql" \ public.ecr.aws/o0r1r5q2/galley-mcp:latest

# Enable debug mode docker run -i -e X_API_KEY="your_key" -e MCP_DEBUG=true public.ecr.aws/o0r1r5q2/galley-mcp:latest # Silent mode (default) docker run -i -e X_API_KEY="your_key" public.ecr.aws/o0r1r5q2/galley-mcp:latest

# Enable introspection (default) docker run -i -e X_API_KEY="your_key" public.ecr.aws/o0r1r5q2/galley-mcp:latest # Disable introspection for production docker run -i -e X_API_KEY="your_key" -e DISABLE_INTROSPECTION=true public.ecr.aws/o0r1r5q2/galley-mcp:latest

# Read-only mode (default) docker run -i -e X_API_KEY="your_key" public.ecr.aws/o0r1r5q2/galley-mcp:latest # Allow only explicit mutations from operation files docker run -i -e X_API_KEY="your_key" -e ALLOW_MUTATIONS=explicit public.ecr.aws/o0r1r5q2/galley-mcp:latest # Allow LLM to build mutations (use with caution) docker run -i -e X_API_KEY="your_key" -e ALLOW_MUTATIONS=all public.ecr.aws/o0r1r5q2/galley-mcp:latest

docker run -i \ -e X_API_KEY="prod_api_key_here" \ -e ENDPOINT="https://app.galleysolutions.com/graphql" \ -e INTROSPECT_ENDPOINT="https://app.galleysolutions.com/graphql" \ -e APOLLOGRAPHQL_CLIENT_NAME="production-server@prod-host" \ -e DISABLE_INTROSPECTION=true \ -e ALLOW_MUTATIONS=none \ public.ecr.aws/o0r1r5q2/galley-mcp:latest

docker run -i \ -e X_API_KEY="prod_api_key_here" \ -e ENDPOINT="https://app.galleysolutions.com/graphql" \ -e INTROSPECT_ENDPOINT="https://app.galleysolutions.com/graphql" \ -e APOLLOGRAPHQL_CLIENT_NAME="production-server@prod-host" \ -e DISABLE_INTROSPECTION=true \ -e ALLOW_MUTATIONS=explicit \ public.ecr.aws/o0r1r5q2/galley-mcp:latest

docker run -i \ -e X_API_KEY="dev_api_key_here" \ -e USER_DIRECTORY="/custom/operations" \ -e MCP_DEBUG=true \ -e ALLOW_MUTATIONS=all \ -v ./custom-operations:/custom/operations \ public.ecr.aws/o0r1r5q2/galley-mcp:latest

docker run -i \ -e X_API_KEY="staging_api_key_here" \ -e STAGING=true \ -e APOLLOGRAPHQL_CLIENT_NAME="staging-server@staging-host" \ public.ecr.aws/o0r1r5q2/galley-mcp:latest

Install Claude Desktopfromhttps://claude.ai/download

{ "mcpServers": { "galley": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "X_API_KEY=your_api_key_here", "-e", "DISABLE_INTROSPECTION=true", "-e", "ALLOW_MUTATIONS=none", "public.ecr.aws/o0r1r5q2/galley-mcp:latest" ], "env": {} } } }

{ "mcpServers": { "galley": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "X_API_KEY=your_api_key_here", "-e", "ALLOW_MUTATIONS=explicit", "public.ecr.aws/o0r1r5q2/galley-mcp:latest" ], "env": {} } } }

Restart Claude Desktopto load the MCP server

Add MCP Configurationin Cursor settings:

- Open Settings → Extensions → MCP
- Add new server configuration:

{ "name": "galley", "command": "docker", "args": [ "run", "--rm", "-i", "-e", "X_API_KEY=your_api_key_here", "public.ecr.aws/o0r1r5q2/galley-mcp:latest" ] }

Enable the MCP serverin Cursor's MCP panel
-

Install VS Codefromhttps://code.visualstudio.com

{ "mcp.servers": { "galley": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "X_API_KEY=your_api_key_here", "public.ecr.aws/o0r1r5q2/galley-mcp:latest" ] } } }

Add your own GraphQL operations by mounting a custom directory:

# Create custom operations directory mkdir -p ./my-operations # Add your .graphql files echo 'query MyCustomQuery { viewer { id } }' > ./my-operations/MyQuery.graphql # Run with custom operations docker run -i \ -e X_API_KEY="your_api_key" \ -e USER_DIRECTORY="/custom" \ -v ./my-operations:/custom \ public.ecr.aws/o0r1r5q2/galley-mcp:latest

The server automatically introspects the Galley GraphQL schema on startup. The schema is saved to/app/schema.graphqland used by the Apollo MCP Server.

- Mandatory execution: Cannot be skipped or disabled
- Fail-fast behavior: Server stops if introspection fails
- Authentication: Uses same credentials as MCP operations
- Real-time schema: Always gets the latest schema on startup
- Client identification: Sendsapollographql-client-nameheader for tracking

- Apollo MCP Server: Latest version installed to/usr/local/bin
- Rover: Apollo's GraphQL CLI tool for schema introspection
- Debian Bookworm Slim: Lightweight base image with glibc support

Enable debug mode for detailed output and troubleshooting:

# Enable debug mode for verbose logging docker run -i -e X_API_KEY="your_api_key" -e MCP_DEBUG=true public.ecr.aws/o0r1r5q2/galley-mcp:latest # View container logs docker logs <container_id> # Run interactively to see all output docker run -it -e X_API_KEY="your_api_key" -e MCP_DEBUG=true public.ecr.aws/o0r1r5q2/galley-mcp:latest # Test with different endpoints in debug mode docker run -i \ -e X_API_KEY="your_api_key" \ -e MCP_DEBUG=true \ -e INTROSPECT_ENDPOINT="https://staging-app.galleysolutions.com/graphql" \ public.ecr.aws/o0r1r5q2/galley-mcp:latest

- Shows all configuration values
- Displays Rover introspection command and output
- Shows schema statistics (lines, file size)
- Enables Apollo MCP Server debug logging
- Displays authentication method being used

galley-mcp/ ├── Dockerfile # Docker container with Apollo MCP Server + Rover ├── entrypoint.sh # Main startup script with mandatory introspection ├── introspect-schema.sh # Schema introspection script using Rover ├── operations/ # GraphQL operations directory │ └── GetRecipesByName.graphql # Example Galley recipe query └── README.md # This comprehensive guide

- entrypoint.sh: Orchestrates schema introspection and server startup
- introspect-schema.sh: Uses Rover to fetch the latest Galley GraphQL schema
- operations/: Contains your GraphQL operations (queries, mutations, subscriptions)
- Dockerfile: Multi-stage build with Apollo MCP Server and Rover pre-installed

The project includes automated CI/CD using GitHub Actions with two specialized workflows:

- Auto-versioning: Automatically increments patch version from latest tag
- GitHub Releases: Creates release with auto-generated notes
- Multi-architecture builds: Builds forlinux/amd64andlinux/arm64
- Multiple Docker tags: Publisheslatest,v1.0.1, and1.0.1tags
- Release documentation: Includes Docker image URLs and commit info

Example:Push to master → Createsv1.0.1release + publishes Docker images

- Push todevelopbranch
- Pull requests tomaster

- Development builds: Publishesdeveloptag for development branch
- PR validation: Builds (but doesn't publish) for pull requests
- Multi-architecture: Supports bothlinux/amd64andlinux/arm64
- Caching: Uses GitHub Actions cache for faster builds

- latest- Latest stable release from master branch
- v1.0.1,1.0.1- Semantic version tags from releases
- develop- Latest development version from develop branch

To set up the CI/CD pipeline, configure these GitHub repository secrets:

- AWS_ACCESS_KEY_ID: AWS access key for ECR push permissions
- AWS_SECRET_ACCESS_KEY: AWS secret key for ECR push permissions

Permissions:The release workflow needscontents: writepermission (automatically configured).

The ECR repository needs to be created as a public repository inus-east-1region with the namegalley-mcp.

# Verify your API key is correct docker run -i -e X_API_KEY="your_key" public.ecr.aws/o0r1r5q2/galley-mcp:latest # Check if endpoint is accessible curl -H "X-API-KEY: your_key" https://app.galleysolutions.com/graphql

# Check network connectivity to introspection endpoint docker run --rm -e X_API_KEY="your_key" public.ecr.aws/o0r1r5q2/galley-mcp:latest ping -c 3 app.galleysolutions.com # Test GraphQL endpoint manually curl -X POST -H "Content-Type: application/json" \ -H "X-API-KEY: your_key" \ -d '{"query": "{ __schema { types { name } } }"}' \ https://app.galleysolutions.com/graphql # Check if introspection endpoint is different from operation endpoint docker run -i \ -e X_API_KEY="your_key" \ -e INTROSPECT_ENDPOINT="https://staging-app.galleysolutions.com/graphql" \ public.ecr.aws/o0r1r5q2/galley-mcp:latest # Verify authentication method # Try with Bearer token instead of X-API-KEY docker run -i -e GALLEY_AUTH_TOKEN="your_token" public.ecr.aws/o0r1r5q2/galley-mcp:latest

# Verify Apollo MCP Server is installed correctly docker run --rm public.ecr.aws/o0r1r5q2/galley-mcp:latest which apollo-mcp-server docker run --rm public.ecr.aws/o0r1r5q2/galley-mcp:latest apollo-mcp-server --version # Check if schema file exists after introspection docker run --rm -e X_API_KEY="your_key" public.ecr.aws/o0r1r5q2/galley-mcp:latest ls -la /app/schema.graphql

# Check Docker is running docker --version # Pull latest base image docker pull debian:bookworm-slim # Rebuild without cache docker build --no-cache -t galley-mcp .

- Check startup logs:docker logs <container_id>- Shows introspection and startup process
- Verify authentication: Ensure your X-API-KEY or Bearer token is valid
- Test endpoints: Confirm both introspection and operation endpoints are accessible
- Check Docker: Make sure you're using the latest Docker version
- Rebuild image: Trydocker build --no-cache -t galley-mcp .to force fresh build

When everything works correctly, you should see: