MCP Troubleshooting Guide

Having issues with the OpenGraph MCP server? This guide covers common problems and their solutions across all supported clients.

Quick Diagnostic Steps

Before diving into specific issues, try these steps:

Restart your AI client – Many issues are resolved by a full restart (not just reload)
Verify Node.js – Run node --version in terminal (need 18+)
Check your App ID – Verify it's correct at dashboard.opengraph.io
Validate JSON – Paste your config at jsonlint.com

Common Issues

MCP tools not appearing

If the OpenGraph tools don't show up in your AI assistant:

Fully restart the application (quit and reopen, don't just reload)
Check config file location is correct for your client (see Install Hub)
Ensure your JSON has the correct key (mcpServers for most clients, context_servers for Zed)
Verify no syntax errors in your config (trailing commas, missing quotes)

"Command not found" errors

This usually means Node.js or npx is not in your PATH:

Check Node.js installation

# Check if Node.js is installed
node --version

# Check if npx is available
npx --version

# If not found, install Node.js from https://nodejs.org

"Invalid App ID" or authentication errors

Double-check your App ID in the dashboard
Make sure you're using the App ID, not the API key or account email
Verify the environment variable is spelled correctly (OPENGRAPH_APP_ID)

JSON parse errors

Common JSON mistakes: trailing commas after the last item, using single quotes instead of double quotes, or missing closing braces.

Correct JSON format

{
  "mcpServers": {
    "opengraph": {
      "command": "npx",
      "args": ["-y", "opengraph-io-mcp"],
      "env": {
        "OPENGRAPH_APP_ID": "your-app-id"
      }
    }
  }
}

Log Locations by Client

Find logs to diagnose MCP server issues:

Client	Log Location
Claude Desktop (macOS)	`~/Library/Logs/Claude/`
Claude Desktop (Windows)	`%APPDATA%\Claude\logs\`
Cursor	Help → Toggle Developer Tools → Console
VS Code	View → Output → Select "MCP"
Windsurf	Help → Toggle Developer Tools → Console
Zed (macOS)	`~/Library/Logs/Zed/`
Zed (Linux)	`~/.local/share/zed/logs/`

Config File Locations

Client	Config File Path
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cursor	`~/.cursor/mcp.json`
VS Code	`.vscode/mcp.json` (project) or user settings
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Zed	`~/.config/zed/settings.json`

Testing the MCP Server Directly

You can test if the OpenGraph MCP server works outside of your AI client:

Test MCP server

# Set your App ID
export OPENGRAPH_APP_ID=your-app-id

# Run the server (it will wait for input)
npx -y opengraph-io-mcp

# If it starts without errors, the server is working
# Press Ctrl+C to exit

If the server fails to start here, the issue is with Node.js or the package installation, not your client configuration.

Frequently Asked Questions

Do I need Node.js installed?

Yes. The MCP server uses npx which requires Node.js 18 or later. Download it from nodejs.org.

Is SSE (Server-Sent Events) still supported?

While the MCP server supports HTTP/SSE transport, most clients now prefer stdio transport. SSE works but stdio is recommended for simplicity and security.

How do I keep my App ID secret?

Your App ID is stored in your local config file and never sent to the AI model. For VS Code, use the inputs feature to avoid storing it in files at all.

Why does my MCP server not appear after restart?

Common reasons:

Config file is in the wrong location
JSON syntax error in the config
Using wrong key name (mcpServers vs context_servers)
Node.js not in system PATH