Giant Swarm Search MCP
giantswarm/search-mcp
Busca integrada na documentação e handbook da Giant Swarm para assistentes IA
Ver no GitHubServidor MCP que fornece acesso a busca na documentação pública, handbook e intranet da Giant Swarm. Implementado em Go com suporte a transportes stdio e HTTP, permite que assistentes de IA pesquisem e leiam recursos técnicos da plataforma.
Instalação
npx convez-ai giantswarm/search-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Pesquisar documentação técnica da Giant Swarm em contexto de IA
- Acessar handbook e runbooks operacionais via assistente IA
- Integrar conhecimento da Giant Swarm em fluxos de automação com Claude
Veredito

MCP robusto e bem estruturado em Go para acesso organizado à base de conhecimento da Giant Swarm. Suporte a autenticação OAuth e múltiplos transportes o torna adequado para integração em diferentes ambientes; documentação clara facilita setup e uso.
README
A tradução para o português deste README ainda está na fila.
Giant Swarm Search MCP Server
An MCP (Model Context Protocol) server that provides AI assistants with search access to Giant Swarm's public documentation and handbook.
Features
- Search public Giant Swarm documentation
- Read and convert documentation pages to Markdown
- Support for both stdio and HTTP transports
- Fast and efficient Go implementation
Quick Start
Cursor
- Open Settings → Tools & MCP
- Click New MCP Server
- Edit the settings like this:
"giantswarm-search": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"gsoci.azurecr.io/giantswarm/search-mcp:TAG",
"serve"
]
}
or alternatively with the binary installed
"giantswarm-search": { "command": "search-mcp", "args": ["serve"] }
Make sure to adapt the version TAG to the version you intend to use. [Check here](https://oci.dag.dev/?repo=gsoci.azurecr.io%2Fgiantswarm%2Fsearch-mcp) for available versions.
### Installation
#### Using Go
```bash
go install github.com/giantswarm/search-mcp@latest
Using Docker
# Pull the image
docker pull gsoci.azurecr.io/giantswarm/search-mcp:TAG
# Run with stdio transport (for direct interaction)
docker run -i --rm gsoci.azurecr.io/giantswarm/search-mcp:TAG serve
# Run with HTTP transport (for network access)
docker run -d -p 8080:8080 \
gsoci.azurecr.io/giantswarm/search-mcp:TAG \
serve --transport=streamable-http --http-addr=:8080
# Check version
docker run --rm gsoci.azurecr.io/giantswarm/search-mcp:TAG version
From Source
git clone https://github.com/giantswarm/search-mcp
cd search-mcp
make build
Usage
Running the Server
# Run with stdio transport (default, for Cursor)
search-mcp
# or explicitly:
search-mcp serve
# Run with HTTP transport
search-mcp serve --transport=streamable-http --http-addr=:8080
# Bound MCP request bodies at 512 KiB (default 1 MiB; larger ones get 413)
search-mcp serve --transport=streamable-http --max-request-body-bytes=524288
# Run with debug logging
search-mcp serve --debug
# Show version
search-mcp version
Available Tools
The server provides these tools to AI assistants; docs/tools.md has every description and input schema exactly as a model reads them.
| Tool | Purpose |
|---|---|
search | Search docs, release notes, handbook, blog posts and, when signed in, the intranet |
search_docs | Search only the public documentation at docs.giantswarm.io |
search_runbook | Find an operations runbook in the intranet. Requires authentication. |
read_docs_index | List the documentation pages of docs.giantswarm.io (llms.txt, no release notes) |
read_docs_url | Read one docs.giantswarm.io page |
read_handbook_url | Read one handbook.giantswarm.io page |
read_intranet_url | Read one intranet.giantswarm.io page. Requires authentication. |
Tool descriptions lead with a summary line of at most 120 runes, built with tooldesc.Describe from mcp-toolkit; TestToolDescriptions holds them to its budgets and TestToolsDocIsCurrent keeps docs/tools.md current (make tools-doc rewrites it).
Authentication
The MCP server supports OAuth 2.1 authentication for accessing Giant Swarm's internal resources (intranet, runbooks).
Quick Start
HTTP Mode (Streamable HTTP Transport)
-
Set environment variables:
export OAUTH_ISSUER_URL=https://dex.operations.awsprod.gigantic.io export OAUTH_CLIENT_ID=searchmcp # export OAUTH_CLIENT_SECRET=<your-secret> # Optional - only if client requires a secret -
Run in HTTP mode:
search-mcp serve --transport=streamable-http --http-addr=:8080 -
Authenticate:
- Visit http://localhost:8080/oauth/login
- Sign in with your Giant Swarm credentials
- You're authenticated!
Shared HTTP server behind an MCP gateway
A server that many people reach through an MCP gateway (for example muster) takes each caller's identity from the request instead of one process-wide login:
export FORWARDED_TOKEN_ISSUER_URL=https://dex.operations.awsprod.gigantic.io
export FORWARDED_TOKEN_AUDIENCE=searchmcp
search-mcp serve --transport=streamable-http --http-addr=:8080
The gateway forwards the caller's bearer token (muster forwardToken, or a token exchanged at this issuer). The server checks its signature, issuer, audience and expiry, uses it for that request's intranet calls only, and never stores it. A call without a valid token gets an authentication error. With forwarded tokens configured, the OAUTH_* login and its /oauth/login endpoint are not used. The intranet accepts tokens of the issuer above, so the token the gateway forwards must come from it.
Stdio Mode (Claude Desktop, Cursor, etc.)
-
Set environment variables:
export OAUTH_ISSUER_URL=https://dex.operations.awsprod.gigantic.io export OAUTH_CLIENT_ID=searchmcp # export OAUTH_CLIENT_SECRET=<your-secret> # Optional - only if client requires a secret -
Run in stdio mode (default):
search-mcp serve -
Authenticate when needed:
- When you use an intranet tool (like
read_intranet_url), the server will display:- A verification URL (e.g., http://localhost:8080/device)
- A device code (e.g., ABCD-EFGH)
- Visit the URL in your browser and enter the code
- Sign in with your Giant Swarm credentials
- Return to your MCP client and retry the tool
- You're now authenticated!
- When you use an intranet tool (like
Note: Stdio mode uses OAuth Device Authorization Grant (RFC 8628). The server automatically starts a background HTTP server on port 8080 for device authorization.
What Requires Authentication?
-
✅ Public tools (no auth required):
read_docs_index- List the documentation pages of docs.giantswarm.ioread_docs_url- Read one documentation pageread_handbook_url- Read one handbook pagesearch_docs- Search only the public documentationsearch- Search docs, release notes, handbook and blog posts; with sign-in also the intranet
-
🔒 Intranet tools (authentication required):
read_intranet_url- Read intranet pagessearch_runbook- Search DevOps runbooks
A server over streamable HTTP without OAUTH_ISSUER_URL or FORWARDED_TOKEN_ISSUER_URL does not advertise the intranet tools; over stdio they stay and explain how to configure OAuth.
Token Storage
Tokens are encrypted and stored at:
- Linux:
~/.config/giantswarm/tokens.enc - macOS:
~/Library/Application Support/giantswarm/tokens.enc - Windows:
%APPDATA%\giantswarm\tokens.enc
Tokens are automatically refreshed before expiration.
For more details, see Authentication Guide.
Configuration
Command-Line Flags
--transport: Transport type -stdioorstreamable-http(default:stdio)--http-addr: HTTP server address (default::8080)--http-endpoint: HTTP endpoint path (default:/mcp)--max-request-body-bytes: Largest MCP request body accepted over streamable HTTP, in bytes; larger ones get 413 (default:1048576, at least 1)--debug: Enable debug logging--version: Show version information
Known Issues / TODO
None at this time.
Troubleshooting
Connection errors
- Verify your network connection
- Check that docs.giantswarm.io is accessible
Debug logging
Enable debug logging to see detailed information:
search-mcp serve --debug
Building from source
If you encounter issues with the pre-built binaries:
git clone https://github.com/giantswarm/search-mcp
cd search-mcp
go build -o search-mcp .
./search-mcp version
Development
For development setup, building from source, and contributing:
# Clone repository
git clone https://github.com/giantswarm/search-mcp
cd search-mcp
# Install dependencies
go mod download
# Build
make build
# Run tests
make test
# Run locally
make run
See Development Guide for detailed instructions.
Technical Documentation
- Architecture - How the server works internally
- Security - Security considerations and best practices
- Development - Development setup and contribution guide
License
Apache License 2.0 - See LICENSE file for details.