Troubleshooting

"ExceptionGroup: unhandled errors in a TaskGroup"

Usually means the CLI couldn’t establish an MCP session.

Checklist

1. Is the server running?

2. Probe the URL directly: curl -I http://127.0.0.1:6288/sse (look for 200 OK).

3. Try matrix mcp probe --url ... --json and inspect the error.

4. Endpoint mismatch

5. Your server exposes /sse, older code might use /messages/.

6. The CLI retries once with the alternate path automatically.

7. Tool name mismatch

8. Server exposes chat, but you called watsonx-chat.

9. The CLI now prints tool names on failures.

10. Stale lock

11. If matrix run says locked, run matrix stop <alias> or remove ~/.matrix/state/<alias>/runner.lock.json.

12. TLS / corporate CA

13. Set SSL_CERT_FILE or REQUESTS_CA_BUNDLE to your CA bundle.

Gateway 401 during install

Set MCP_GATEWAY_TOKEN or pass --gw-token in your PoC scripts.

Local wheels

Ensure your virtualenv resolves your dev wheels first, e.g. install matrix-python-sdk-*.whl before matrix-cli.