🩺 Troubleshooting

🔌 Server not showing in the MCP list

• Ensure opencode is installed: which opencode.
• Check your Node.js version: node --version (must be ≥ 20).
• Try running the server manually: npx @kud/mcp-opencode.

🚫 "failed to create session" error

• Make sure opencode is installed and at least one provider is configured.
• Run opencode models to verify your setup.

⚠️ "The requested model is not supported" error

• The model ID exists in opencode's registry but isn't supported by the provider's API.
• Use list_models and pick a working model — e.g. github-copilot/gpt-4.1 instead of github-copilot/claude-sonnet-4.

📋 Model not in the list

• The model list reflects your opencode configuration, not the full marketplace.
• Run opencode models in your terminal to see the same list the server exposes.

🔎 Inspecting tools manually

For testing tools without a full AI client, the MCP Inspector runs against the built server:

npm run inspect

It opens an interactive UI at http://localhost:5173.

🗂️ list_sessions doesn't show my TUI session

• A plain opencode opens no port, so there is nothing to discover. Start it with opencode --port <free port> (4097 upwards; 4096 is the MCP's own).
• Check what the MCP can see: lsof -nP -a -c opencode -iTCP -sTCP:LISTEN.
• If MCP_OPENCODE_URL is set, discovery is off and only that server is used.

⏳ send says "still running"

• The reply took longer than timeout_seconds (default 600). opencode is still working on it; call read with the same session ID to fetch the answer.