Tips and Troubleshooting

Prompt suggestions for getting good results from your AI assistant, fixes for the issues seen most often during testing, and the known limitations.

Getting the best results

Start with a connection test

Before trying anything else, confirm that your AI application can talk to DisplayNet Connect:

"Use displaynet_version to check if we're connected."

A successful response includes the DisplayNet Connect version, API version, and build timestamp. If this fails, see Common issues below.

Name DisplayNet explicitly

If your AI assistant is also connected to other tools (your file system, the web, other MCP servers), a vague prompt may not make it obvious that you're asking about your DisplayNet system. Being explicit avoids the AI guessing wrong or asking you to clarify.

Good: "Can you check on my DisplayNet devices?"

Less reliable: "Can you check on my devices?"

This matters most early in a conversation, before the AI has context about what you are working on. Once you have established the topic, shorter prompts usually work fine.

Use device names, not MAC addresses

DisplayNet Manager lets you give devices human-friendly names like Camera 1, Lobby Display, or Stage Laptop. AI assistants work best when you use these names in your prompts. The AI will figure out the underlying device IDs and MAC addresses on its own.

Good: "Show me what Camera 1 is displaying."

Less reliable: "Show me what device 6cdffb011b17 is displaying."

Be specific about what you want

Vague prompts produce vague results. The more specific your request, the more useful the answer.

Good: "List all devices currently routed to the main display, and tell me which one has the strongest signal."

Less useful: "How is everything?"

Helpful prompt patterns

These prompts work well across all tested AI applications. Use them as a starting point and adapt to your situation.

What you want to know	Try saying
Daily health check	"Are all DisplayNet devices healthy? Flag anything that looks wrong."
Current routing	"Show me what is currently routed to each display."
Specific device status	"What is the signal status on Display 1?"
Trace a signal	"Trace the path from Camera 1 to the main display."
Recent activity	"What events have happened in the last hour?"
Live thumbnail	"Show me what Camera 1 is currently displaying."
Make a change	"Route the Apple TV to Display 2."
Get help on a feature	"How do I create a video wall?"

Confirm before changing anything

For prompts that change the system (routing, presets, configuration), ask the AI to confirm before it acts. Example: "Route the Apple TV to Display 2, but tell me what you are about to do before you do it."

---

Common issues

"I don't see DisplayNet tools in my AI assistant"

Symptom: Your AI application doesn't show DisplayNet tools, or it reports that it has no MCP access.

Try these in order:

1. Start a new conversation. MCP connections are established when a conversation starts. If the connection failed at startup, a new conversation will retry.
2. Fully restart the AI application. Closing the window is not always enough. See Connect Your AI Application for the right way to fully quit each application.
3. Validate your config file. A missing comma, bracket, or quote will break the JSON. Paste your config into jsonlint.com to check.
4. Check the log files. See Log locations below for where to find them on each platform.

Connection failed

Symptom: Your AI application reports that it cannot connect, or commands time out.

1. Verify the server IP address. Use the numeric IP (like 10.241.254.247), not a hostname like displaynet.local. Hostnames do not work reliably on all networks.

2. Verify the port. DisplayNet Connect runs on port 7050 by default. If your administrator changed this, use that port instead.

3. Verify your credentials. Try logging into the DisplayNet Manager web interface with the same username and password.

4. Test the connection from a terminal:

   curl -s http://YOUR_SERVER_IP:7050/mcp -X POST \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

   A response (even an error) confirms that DisplayNet Connect is reachable. No response usually means a network or firewall problem.

Special characters in passwords

The following characters can cause problems in JSON config files: " ' $ ` \ (double quote, single quote, dollar sign, backtick, backslash). If your password contains any of these and your config does not work, ask your administrator to set a simpler password for use with DisplayNet Connect.

Application-specific issues

Claude Desktop: "npx not found" or similar

Symptom: Claude Desktop fails to start the MCP connection. The log file mentions npx or node is not found.

Fix: Install Node.js (LTS version) from nodejs.org, then fully quit and restart Claude Desktop.

After installing, verify it works by opening a Terminal (Mac) or Command Prompt (Windows) and typing:

npx --version

If you see a version number, Node.js is correctly installed.

Node.js version managers

If you use a Node.js version manager such as nvm, fnm, or volta, and you see SyntaxError or Cannot find module errors in the Claude Desktop log, your application may be finding the wrong Node.js version. This is a known issue. See your version manager's documentation, or contact your DisplayNet administrator for guidance on overriding the PATH in your Claude Desktop config.

Claude Desktop: First connection takes 10-30 seconds

This is normal. The first time Claude Desktop runs, it downloads the mcp-remote helper tool. After that, startup is fast.

Claude Code: Tools missing even after setup

Symptom: claude mcp list shows DisplayNet, or claude mcp get displaynet confirms it is configured at user scope, but the tools do not appear when you open Claude Code in a project folder.

Cause: An empty .mcp.json file in a parent directory can block your user-level config from loading. Look for files like this:

{
  "mcpServers": {}
}

Fix: From your project directory, check for .mcp.json files in parent folders:

ls -la ../.mcp.json
ls -la ../../.mcp.json

Either delete those files, or add the DisplayNet config to them.

Gemini CLI: "You have exhausted your daily quota" on the first prompt

Symptom: Your very first prompt fails with a "daily quota exhausted" error, even though you have not used Gemini at all today.

Cause: Gemini CLI's model routing can auto-escalate prompts to a Pro model, which has zero free-tier quota. The error message is misleading. The actual problem is that the request was routed to a paid model.

Fix: Always launch with the model flag:

gemini --model gemini-2.5-flash

The model setting in ~/.gemini/settings.json may be overridden by a known bug, so the CLI flag is the reliable workaround.

Antigravity: "serverURL or command must be specified"

Symptom: Antigravity reports an error about serverURL or command when loading the DisplayNet Connect config.

Cause: Antigravity's own AI assistant may suggest httpUrl as the config key. This is incorrect.

Fix: Use serverUrl (camelCase) instead. See the Antigravity setup steps for the full config example.

---

Known limitations

Thumbnails in Claude Desktop

Claude Desktop's AI runs in Anthropic's cloud, not on your local machine. MCP tool calls work because the mcp-remote bridge runs locally, but Claude Desktop's AI cannot download images from your local network. When you ask for a thumbnail, Claude Desktop will return the URL but cannot show the image inline.

Workaround: Open the thumbnail URL in your browser to view it.

For thumbnails directly in chat, use Claude Code, Gemini CLI, or Antigravity instead. These applications run locally and can fetch the image themselves.

Free-tier rate limits

Gemini CLI's free tier has daily request and token limits. Sustained use may require enabling billing on your Google API key.

OpenAI Codex CLI does not offer a free tier. A paid OpenAI API key is required.

Claude Code and Claude Desktop require an Anthropic Pro or Max subscription. There is no free tier for either.

Special characters in passwords

See the warning under Connection failed above. JSON config files do not handle certain characters well.

---

Log locations

When something is not working, the log file usually has the answer.

AI Application	Windows	macOS	Linux
Claude Desktop	Inside %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\logs\	~/Library/Logs/Claude/mcp-server-displaynet.log	~/.config/Claude/logs/mcp-server-displaynet.log
Claude Code	Terminal output	Terminal output	Terminal output
Gemini CLI	Terminal output	Terminal output	Terminal output
OpenAI Codex CLI	Terminal output	Terminal output	Terminal output
Antigravity	Inside the IDE's developer console	Inside the IDE's developer console	Inside the IDE's developer console

Finding Claude Desktop logs on Windows

Claude Desktop on Windows is a sandboxed Microsoft Store application, so log files live in a package-specific folder that is hard to find by browsing. The easiest way is to open Claude Desktop and go to Settings > Developer > Edit Config. The file that opens is in the right folder. The logs subfolder is in the same directory.

---

Getting help

If issues persist after trying the steps above:

1. Check the log file for specific error messages (see Log locations above).
2. Verify the DisplayNet server is running and reachable on your network.
3. Contact your DisplayNet administrator for help with credentials, network configuration, or server-side issues.