mcp-guide

Add an entry under mcp_servers in .agents/omni-agent/config.yaml with either command/args/env for stdio servers or url/headers for HTTP servers. Save the file and run omni-agent /reload-mcp to apply the change.

Stdio servers run as local subprocesses launched with a command like npx, offering low latency. HTTP servers are remote endpoints configured with a url and optional headers, avoiding local process management.

Tools may be hidden by a tools.include whitelist, an enabled: false flag, or a failed connection due to a missing runtime like npx. Check the config filters first, then verify the server actually connects.

OAuth flows require a browser, which fails on headless hosts because the loopback redirect cannot complete. Use SSH port forwarding or paste the redirect URL manually, and run omni-agent mcp login from a new terminal since auto-reload only waits 30 seconds.

Set supports_parallel_tool_calls to false for stateful operations such as Genkit flows, database writes, or anything modifying shared files, to avoid race conditions. Read-only query servers can safely use true.

Prefer include whitelists for servers touching financial data, customer data, or destructive operations. Use exclude blacklists only for low-risk servers, and note that include takes precedence over exclude for the same tool.