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)
Approve the sign-in – If you're using the recommended sign-in method, check that a browser tab opened and you approved the connection
Check your App ID (API key mode) – 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)

Browser doesn't open to sign in

If you're using the recommended sign-in method and no browser tab opens:

Remove the MCP server entry from your config and re-add it
Fully restart your AI client (not just reload)
Check that https://mcp.opengraph.io/mcp is reachable from your network (no VPN or firewall blocking it)

"Invalid App ID" or authentication errors (API key mode)

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 header is spelled correctly (x-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": {
      "url": "https://mcp.opengraph.io/mcp"
    }
  }
}

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 Hosted Server Directly

You can confirm the hosted OpenGraph MCP server is reachable outside of your AI client with a basic request:

Test the hosted MCP endpoint

curl -i https://mcp.opengraph.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

A response (even an authentication error) means the server is reachable and the issue is with your client configuration or sign-in flow, not connectivity.

Frequently Asked Questions

Do I need Node.js installed?

No. The recommended setup connects to the hosted server by URL, so there's nothing to install. Node.js is only needed if you choose to run the MCP server locally via npx.

Is SSE (Server-Sent Events) still supported?

Yes, the hosted server supports both Streamable HTTP and SSE fallback so it works across all MCP clients.

How do I keep my App ID secret?

If you use the recommended sign-in method, there's no App ID in your config at all. If you use an API key instead, it's 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)
You didn't approve the sign-in prompt in the browser tab