This guide walks through installing eggsearch, configuring it, and using it from an MCP-compatible client such as CodeGG.
- Rust 1.89 or later installed when building from source
- An MCP-compatible client (CodeGG, Claude Code, or any client supporting MCP over stdio or Streamable HTTP)
curl -fsSL https://github.com/eggstack/eggsearch/releases/latest/download/install.sh | bashOn Windows PowerShell:
irm https://github.com/eggstack/eggsearch/releases/latest/download/install.ps1 | iexFor a source installation:
cargo install eggsearch --lockedOr build from source:
git clone https://github.com/eggstack/eggsearch.git
cd eggsearch
cargo build --releaseThe binary is written to target/release/eggsearch.
The config file is optional. eggsearch uses platform-specific locations:
$XDG_CONFIG_HOME/eggsearch/config.toml on Linux (usually
~/.config/eggsearch/config.toml), ~/Library/Application Support/eggsearch/config.toml
on macOS, and %APPDATA%\eggsearch\config.toml on Windows. It uses built-in defaults when no config file exists.
If you add a [search] table, include all of its required fields. Partial
[search] tables are rejected. See Configuration for the full
reference.
A minimal config:
[search]
mode = "live"
default_max_results = 10
max_results_cap = 50
max_query_chars = 512
timeout_ms = 8000
default_providers = ["duckduckgo", "brave", "yahoo"]
[search.providers]
duckduckgo = true
brave = true
startpage = true
yahoo = true
[fetch]
enabled = trueFor coding work with GitHub integration:
[search]
mode = "live"
default_max_results = 10
max_results_cap = 50
max_query_chars = 512
timeout_ms = 8000
default_providers = ["duckduckgo", "brave"]
[search.providers]
duckduckgo = true
brave = true
[search.api.github_code]
enabled = true
api_key_env = "GITHUB_TOKEN"
[search.api.github_issues]
enabled = true
api_key_env = "GITHUB_TOKEN"
[search.api.github_releases]
enabled = true
api_key_env = "GITHUB_TOKEN"
[fetch]
enabled = trueSet the GITHUB_TOKEN environment variable before starting the server.
Start the server on stdio transport:
eggsearch mcp stdioOr set a custom config path:
eggsearch --config /path/to/config.toml mcp stdioThe server reads MCP JSON-RPC messages from stdin and writes responses to stdout.
For a persistent local endpoint instead, run:
eggsearch mcp serve --bind 127.0.0.1:11320 --path /mcpCheck http://127.0.0.1:11320/healthz before connecting. This mode is
foreground-only and loopback-only; the installer does not register it as a
service.
Configure your MCP client to launch eggsearch as a child process over stdio, or declare the explicit local HTTP endpoint if the client supports Streamable HTTP. The exact configuration depends on your client.
In your CodeGG MCP server configuration:
{
"mcpServers": {
"eggsearch": {
"command": "eggsearch",
"args": ["mcp", "stdio"]
}
}
}An HTTP-capable client can use the persistent endpoint explicitly:
{
"mcpServers": {
"eggsearch-http": {
"url": "http://127.0.0.1:11320/mcp"
}
}
}{
"mcpServers": {
"eggsearch": {
"command": "eggsearch",
"args": ["mcp", "stdio"]
}
}
}For a custom config path, set the environment variable:
{
"mcpServers": {
"eggsearch": {
"command": "eggsearch",
"args": ["mcp", "stdio"],
"env": {
"EGGSEARCH_CONFIG": "/path/to/config.toml"
}
}
}
}A typical research flow uses three tools:
web_search({
"query": "rust async runtime comparison",
"intent": "research",
"max_results": 10
})
Returns a list of source cards with next_actions and suggested_fetches.
Follow sanitized next_actions without another discovery round trip; ignore
unknown tool names. Keep the immediate palette small (web_search,
repo_search, optionally web_fetch) and load specialists only when needed.
See Progressive Disclosure.
web_fetch({
"url": "https://tokio.rs/blog/2020-04-preparing-for-tokio-0-3",
"extract_mode": "markdown",
"max_chars": 12000
})
Returns extracted text from the selected URL.
batch_fetch({
"items": [
"https://docs.rs/axum/latest/axum/",
"https://docs.rs/actix-web/latest/actix_web/"
]
})
Fetches multiple URLs in bounded parallel.
Hosts may inspect provider_status during bootstrap; agents call it only when provider availability itself is relevant or troubleshooting is required. It is diagnostic, not a normal first research step:
provider_status({})
This returns provider health, server capabilities, tool capabilities, and workflow recipes.
- MCP Integration Guide -- harness-developer reference (progressive disclosure, trust boundary, workflows); this quickstart is the end-user path into that guide
- Configuration -- full config reference with all options and defaults
- Provider Setup -- how to enable and configure individual providers
- Tool Matrix -- compact reference for all 10 MCP tools
- Agent Workflows -- recommended tool call sequences and recipes