giantswarm/search-mcp

Giant Swarm Search MCP Server

An experimental MCP (Model Context Protocol) server that provides AI assistants with search access to Giant Swarm's documentation, handbook, and intranet.

Features

• Search public Giant Swarm documentation (no authentication required)
• Search internal intranet resources (with optional authentication)
• Automatic endpoint selection based on authentication status
• Read and convert documentation pages to Markdown
• Session persistence across restarts

Quick Start

Cursor

1. Open Settings → Tools & MCP
2. Click New MCP Server
3. Edit the settings like this:

"giantswarm-search": {
   "command": "docker",
   "args": [
      "run",
      "-i",
      "--rm",
      "-e",
      "INTRANET_SESSION_COOKIE",
      "gsoci.azurecr.io/giantswarm/search-mcp:0.0.1"
   ],
   "env": {
      "INTRANET_SESSION_COOKIE": "..."
   }
}

Make sure to adapt the version tag (0.0.1 in the example above) to the version you intend to use. Check here for available versions.

Note that INTRANET_SESSION_COOKIE is only required if you want to access intranet content. Read on for instructions on how to obtain the right value.

Optional: Authenticate for intranet access

To access internal Giant Swarm resources, set up authentication:

1. Visit intranet.giantswarm.io and login with GitHub
2. Open browser Developer Tools (F12) → Application → Cookies
3. Copy the _oauth2_proxy cookie value
4. Set INTRANET_SESSION_COOKIE environment variable value in the MCP configutation.

Usage

The server provides these tools to AI assistants:

search(term: str)

Search Giant Swarm documentation.

• Without authentication: Public docs only (docs.giantswarm.io, blog, etc.)
• With authentication: Public + intranet resources

search_runbook(term: str)

Search DevOps runbooks in the intranet. Requires authentication.

search_ops_recipe(term: str)

Search Ops Recipes (runbooks) in the intranet. Requires authentication.

read_handbook_url(url: str)

Read content from Giant Swarm handbook. No authentication required.

read_intranet_url(url: str)

Read content from Giant Swarm intranet. Requires authentication.

Configuration

Environment Variables

• INTRANET_SESSION_COOKIE: OAuth2 proxy session cookie (optional, for intranet access)
• PYTHONLOGLEVEL: Logging level - DEBUG, INFO, WARNING, or ERROR (optional)

Copy env.example to .env and customize as needed.

Troubleshooting

Limited search results

You're in public-only mode. To access intranet resources, set the INTRANET_SESSION_COOKIE environment variable following the authentication setup instructions above.

"Authentication required" error

Your session cookie may have expired. To fix this:

1. Log into https://intranet.giantswarm.io/ again
2. Get a fresh cookie value:
   • Open the developer tools (F12 or Cmd + Option + I)
   • Go to Application → Cookies → https://intranet.giantswarm.io
   • Select the cookie named _oauth2_proxy
   • Copy the cookie value
3. Update your environment variable:
   • In Cursor: Settings → Tools & MCP → Edit giantswarm-search → Update INTRANET_SESSION_COOKIE
   • Or in terminal: export INTRANET_SESSION_COOKIE="your_new_cookie_value"

Connection errors

• Verify your network connection
• Check that docs.giantswarm.io is accessible
• For intranet access, ensure your credentials are valid

Technical documentation

• - How the server works internally
• - Security considerations and best practices
• - Development setup and contribution guide