The server disconnects before initialization
Confirm the client runs mcp-aide with serve in its arguments, using an absolute path when the client's PATH differs. Check options with mcp-aide serve --help, and keep the stderr diagnostics.
failed to execute aide
The executable cannot start, the projectDir is invalid, or output collection failed. Confirm both exist in the server's environment, set serve --aide-binary /absolute/path/to/aide if needed, and restart the connection.
The result is a tool error or an argument is refused
Read isError first. A failed command's text holds exitCode, stdout, stderr and truncated. Common refusals: supply caCert and caKey together or neither, choose generateCa or an existing pair, and add confirmPurge=true only with purge=true. Use exact camel-case names and real booleans; an unknown property can be ignored.
Setup passes but create fails
The setup query only inspects. Apply missing host setup through your AIDE workflow, then run it again. Create also needs a valid project, runtime access and the host helper, and it refuses an existing cluster. Check the real hostname over HTTPS after create.
Project DNS or HTTPS trust breaks
Project DNS needs a running dnsmasq that reads the file AIDE writes; setup installs the package but does not start it. If trust breaks after a start with ca.generate:true, recover the original pair and configure its paths before starting again. The AIDE problems page has both procedures.
Deletion returns planned:true
The request lacks confirm:true. The reply is a reminder only and lists nothing. Query the project and cluster first, then repeat with confirmation. Cleanup is best effort, so check named volumes when data removal matters.
The selected cluster and the project disagree
action:select changes the AIDE default and kubectl context; it does not edit .aide.yaml. Create, start, stop, status and delete still use the cluster named in the project file you pass.
A route change fails or reaches the wrong backend
The Service must already exist in the chosen cluster and namespace. Use a literal IPv4 endpoint and confirm the backend is listening. After a partial failure, inspect selectors, Endpoints and EndpointSlices, or use reset, and test through the application's normal URL.
Output is incomplete or a call times out
truncated:true means one stream exceeded 16 KiB. The server waits up to 30 minutes, and a timeout returns no output and undoes nothing. Inspect the cluster before retrying a long change.
What you getThe failed or incomplete AIDE operation identified, with a safe next step.