> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-docs.synta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for Synta MCP

Having trouble with Synta MCP? This guide covers the most common issues and how to resolve them.

## Common Issues

<AccordionGroup>
  <Accordion title="AI client not using Synta MCP tools" icon="robot">
    If your AI client isn't calling Synta MCP tools or seems unaware of the MCP connection:

    ### Solution

    1. **Explicitly Mention Synta MCP in Your Prompt**

       Try using a prompt like this:

       ```text theme={null}
       Use synta-mcp to search for the Slack node in n8n
       ```

       This explicitly tells the AI to use the Synta MCP tools.

    2. **Restart Your AI Client**
       * Completely quit your AI client (don't just close the window)
       * Reopen the application
       * Start a new conversation/chat

    3. **Start a Fresh Chat**
       * Previous conversations may have context that doesn't include MCP awareness
       * Create a new chat window/conversation
       * Try your request again with explicit mention of synta-mcp

    4. **Verify MCP Connection**
       * Check your MCP configuration is still active
       * Look for MCP indicators in your client (e.g., tool icons, MCP badge)
       * If the connection appears inactive (e.g. A red status icon on Cursor), restart your client or reconfigure following the [installation steps](/installation)

    ### Why This Happens

    AI clients may not always automatically use MCP tools unless explicitly prompted, especially in existing conversations or after updates.
  </Accordion>

  <Accordion title="ChatGPT MCP connection fails on first attempt" icon="rotate">
    ChatGPT's MCP integration can be buggy and may not connect on the first try.

    ### Solution

    1. Delete the MCP app from ChatGPT settings
    2. Re-create the app following the [installation steps](/installation)
    3. **Repeat the process 3-5 times** if it doesn't work initially
    4. This is a known ChatGPT limitation, not a Synta issue

    ### Why This Happens

    ChatGPT's MCP implementation is relatively new and can have intermittent connection issues. Retrying the setup process typically resolves the issue.

    ### Note

    ChatGPT only supports OAuth authentication (no API key option). This requires a **Pro, Plus, Business, Enterprise or Education** paid plan.
  </Accordion>

  <Accordion title="ChatGPT MCP becomes unstable or returns &#x22;Resource not found&#x22;" icon="triangle-exclamation">
    After successfully connecting Synta MCP to ChatGPT, you may experience instability where the MCP connection becomes "gone" or tools return "Resource not found" errors during a session.

    ### Common Symptoms

    * Tools work initially, then suddenly fail with "Resource not found"
    * ChatGPT reports the MCP link is "gone" mid-conversation
    * Tools like n8n\_get\_workflow or n8n\_update\_partial\_workflow stop working
    * Connection appears to drop without warning

    ### Solution

    **Use Vanilla Chat Instead of Projects:**

    1. Do NOT use ChatGPT Projects for Synta MCP
    2. Use regular chat conversations (vanilla chat) instead
    3. The MCP connection is more stable in standard chat mode

    ### Why This Happens

    ChatGPT's MCP support is currently flaky and unreliable, especially within Projects. The connection works better in standard chat conversations. This is a known ChatGPT limitation.

    ### Alternative Recommendation

    For more stable MCP connections, consider using:

    * **Cursor** - Excellent MCP support with OAuth or API key
    * **Claude Desktop** - Native MCP support, very stable
    * **Claude Code** - CLI-based, reliable MCP integration

    See the [Installation](/installation) page for setup instructions for these alternatives.
  </Accordion>

  <Accordion title="Authentication errors" icon="key">
    If you're getting authentication or authorization errors:

    ### Solution

    1. **Verify Synta API Key**
       * Ensure you copied the full API key from [synta.io/mcp](https://synta.io/mcp)
       * Check for extra spaces or newlines
       * Make sure the key starts with the correct format

    2. **Check N8N Credentials**
       * Verify your N8N instance URL is accessible
       * Test your N8N API key in a browser or API client
       * Ensure the API key has the correct permissions

    3. **Verify N8N Login Credentials (for self-healing tools)**
       * Check `X-N8n-Login-Email` is set to your n8n account email
       * Check `X-N8n-Login-Password` is set to your n8n account password
       * Required for `n8n_trigger_execution` and `n8n_manage_pindata`
       * Make sure the credentials are correct and the account has appropriate permissions

    4. **Update Configuration**
       * Replace credentials in your config file
       * Restart your AI agent after updating
  </Accordion>

  <Accordion title="MCP server disconnects or times out" icon="plug">
    If the MCP server disconnects during operations or times out:

    ### Common Causes

    * Long-running operations (large workflows, many templates)
    * Network instability
    * Server timeout settings
    * Resource-intensive tool calls

    ### Solution

    1. **Break Down Large Operations**
       * Search templates in smaller batches (use `limit` parameter)
       * Process workflows one at a time instead of bulk operations
       * Use pagination with `cursor` for large result sets

    2. **Use Faster Tool Variants**
       * Use `get_node` with `view: "summary"` for quick property checks
       * Use `n8n_validate_workflow` only after you have narrowed the problem to a specific workflow
       * Use `get_template` with `mode: "nodes_only"` for quick previews

    3. **Increase Timeout Settings**
       * Check your MCP client's timeout configuration
       * Some operations like `n8n_trigger_execution` may need longer timeouts

    4. **Restart the Connection**
       * Clear npx cache: `rm -rf ~/.npm/_npx`
       * Restart your AI agent
       * Verify network stability

    5. **Check Tool Parameters**
       * Ensure `limit` parameters are reasonable (avoid requesting 1000+ items)
       * Avoid `includeConfigExamples` in `get_node` unless needed
       * Disable expensive options like `includeTypeInfo` unless needed
  </Accordion>

  <Accordion title="Execution failures or webhook issues" icon="circle-xmark">
    If workflows fail to execute or webhook triggers don't work:

    ### Choose the Right Tool

    **n8n\_trigger\_execution**:

    * Requires N8N login credentials (`X-N8n-Login-Email`, `X-N8n-Login-Password`)
    * Supports all trigger types: Manual, Chat, Webhook, Form
    * AI automatically detects errors and suggests fixes (self-healing)
    * Full execution data for debugging
    * Works with n8n\_manage\_pindata for testing

    **n8n\_test\_workflow**:

    * External testing for activated workflows
    * Supports: Webhook, Form, Chat triggers

    **n8n\_manage\_pindata**:

    * Requires N8N login credentials (`X-N8n-Login-Email`, `X-N8n-Login-Password`)
    * Save mock data for any node and reuse in test runs
    * Test webhooks/forms without sending real requests
    * Skip API calls during development with saved responses
    * Modes: addPinData, updatePinData, removePinData, readPinData

    ### Common Solutions

    1. **Activate Workflow** (for `n8n_test_workflow`)
       ```json theme={null}
       {
         "id": "workflow-id",
         "operations": [
           {"type": "updateSettings", "settings": {"active": true}}
         ]
       }
       ```

    2. **Verify Trigger Configuration**
       * Workflow has a valid trigger node
       * Webhook path is correctly configured
       * Chat triggers have a valid `chatMessage`

    3. **Debug Failed Executions**
       ```javascript theme={null}
       // Get error details
       n8n_manage_executions({action: "get", id: "exec-id", mode: "error"})

       // Trace multi-workflow chains
       n8n_manage_executions({action: "correlate", executionId: "exec-id"})

       // Re-run failed execution
       n8n_manage_executions({action: "retry", id: "exec-id"})
       ```
  </Accordion>

  <Accordion title="Google Antigravity: tool calls fail with 'connection closed' or 'unexpected end of JSON input'" icon="google">
    If you can list tools but tool execution fails with errors like:

    * `Failure in MCP tool execution: connection closed: calling "tools/call": client is closing: standalone SSE stream: failed to decode event: unmarshaling jsonrpc message: unexpected end of JSON input`
    * `Failure in MCP tool execution: connection closed: calling "tools/call": client is closing: EOF`
    * `mismatching session IDs`

    ### Solution

    1. **Remove and re-add the MCP server in Antigravity**
       * Go to Antigravity settings → MCP Servers
       * Remove the Synta MCP server completely
       * Close Antigravity entirely (not just the conversation)
       * Reopen Antigravity and re-add the server

    2. **Use the correct configuration format**
       ```json theme={null}
       {
         "mcpServers": {
           "synta": {
             "type": "streamable-http",
             "serverUrl": "https://mcp.synta.io/mcp"
           }
         }
       }
       ```
       Setting `"type": "streamable-http"` explicitly tells Antigravity to use the correct transport protocol.

    3. **If errors persist after re-adding**, start a new conversation in Antigravity. The previous conversation may have cached stale session state.

    ### Why This Happens

    Antigravity's MCP client caches session state internally. When a session becomes stale (e.g., after a server update or network interruption), the cached session is never revalidated. This is a [known Antigravity/ADK issue](https://github.com/google/adk-go/issues/399). Removing and re-adding the server forces a fresh connection that bypasses the stale cache.
  </Accordion>

  <Accordion title="Claude Desktop: All tools blocked in Cowork mode ('This tool has been disabled')" icon="lock">
    After a Claude Desktop update, all Synta MCP tools may be discovered (appear in the tool list with full schemas) but every call returns:

    > "This tool has been disabled in your connector settings."

    This only affects **Cowork mode** — the same setup works fine in standard Claude Chat.

    ### Why This Happens

    Claude Desktop now requires MCP server IDs to be either a UUID or a `mcpsrv_*` prefixed string. The default server name `synta-mcp` doesn't match this format, so Cowork discovers the tools but blocks execution. The actual error (`Invalid server ID format. Expected UUID or mcpsrv_* tagged ID.`) only surfaces when you attempt to uninstall the connector — making this particularly hard to debug.

    ### Fix

    <Tabs>
      <Tab title="OAuth">
        1. Go to **Claude** → **Settings** → **Connectors**

        2. Find the Synta MCP connector and click **Delete** to remove it

        3. Click **Add custom connector** and re-add it with the updated name:

           **Name:**

           ```text theme={null}
           mcpsrv_synta
           ```

           **Remote MCP server URL:**

           ```text theme={null}
           https://mcp.synta.io/mcp
           ```

        4. Authenticate with the **same account** you used at [synta.io](https://synta.io)

        5. Restart Claude Desktop (**Cmd+Q**, then reopen)
      </Tab>

      <Tab title="API Key">
        1. Open your Claude Desktop config file:
           * Go to **Claude** → **Settings** → **Developer** → **Edit Config**

        2. Rename the server key from `synta-mcp` to `mcpsrv_synta`:

           **Before:**

           ```json theme={null}
           {
             "mcpServers": {
               "synta-mcp": {
                 "command": "npx",
                 "args": ["..."]
               }
             }
           }
           ```

           **After:**

           ```json theme={null}
           {
             "mcpServers": {
               "mcpsrv_synta": {
                 "command": "npx",
                 "args": ["..."]
               }
             }
           }
           ```

        3. Save the file and restart Claude Desktop (**Cmd+Q**, then reopen)
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Nodes showing as unknown on the canvas" icon="question">
    If workflow nodes appear as "Unknown" on the canvas:

    ### Why This Happens

    Your n8n instance doesn't recognize the node types in the workflow. This typically occurs when:

    * The workflow uses nodes from a newer n8n version
    * Community nodes are not installed
    * Node packages are missing or outdated

    ### Solution

    1. **Update n8n to Latest Version**

       * Check your current version in **Settings** → **About n8n**
       * Update to the latest version:

       **n8n Cloud**: Automatically updated, contact support if issues persist

       **Self-hosted**: Follow your hosting provider's instructions for updating n8n (Docker, npm, etc.)

    2. **Install Missing Community Nodes**
       * Go to **Settings** → **Community nodes**
       * Search for and install any missing community nodes
       * Restart n8n after installation

    3. **Check Node Compatibility**
       * Some nodes may be deprecated or renamed in newer versions
       * Use `n8n_autofix_workflow` to automatically update node types
       * Review the workflow and replace deprecated nodes with current alternatives
  </Accordion>

  <Accordion title="Error: &#x22;Cannot find module body-parser&#x22;" icon="triangle-exclamation">
    This error occurs when npm's cache has corrupted packages for npx.

    ### Solution

    Clear the npx cache and try again:

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      rm -rf ~/.npm/_npx
      ```

      ```powershell Windows (PowerShell) theme={null}
      Remove-Item -Recurse -Force "$env:USERPROFILE\.npm\_npx"
      ```

      ```cmd Windows (Command Prompt) theme={null}
      rmdir /s /q "%USERPROFILE%\.npm\_npx"
      ```
    </CodeGroup>

    After clearing the cache, restart your AI client.

    ### Why This Happens

    The npx cache can sometimes store incomplete or corrupted package installations. Clearing it forces a fresh download of all required packages.
  </Accordion>

  <Accordion title="MCP configuration file doesn't exist" icon="file-slash">
    If you can't find your MCP configuration file, you may need to create it manually.

    ### Solution by Client

    **Cursor**:

    <CodeGroup>
      ```bash macOS/Linux theme={null}
      mkdir -p ~/.cursor && touch ~/.cursor/mcp.json
      ```

      ```powershell Windows (PowerShell) theme={null}
      New-Item -ItemType Directory -Force -Path "$env:APPDATA\Cursor"
      New-Item -ItemType File -Force -Path "$env:APPDATA\Cursor\mcp.json"
      ```

      ```cmd Windows (Command Prompt) theme={null}
      mkdir "%APPDATA%\Cursor" 2>nul
      type nul > "%APPDATA%\Cursor\mcp.json"
      ```
    </CodeGroup>

    **Claude Desktop**:

    <CodeGroup>
      ```bash macOS theme={null}
      mkdir -p ~/Library/Application\ Support/Claude
      touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
      ```

      ```bash Linux theme={null}
      mkdir -p ~/.config/Claude
      touch ~/.config/Claude/claude_desktop_config.json
      ```

      ```powershell Windows (PowerShell) theme={null}
      New-Item -ItemType Directory -Force -Path "$env:APPDATA\Claude"
      New-Item -ItemType File -Force -Path "$env:APPDATA\Claude\claude_desktop_config.json"
      ```

      ```cmd Windows (Command Prompt) theme={null}
      mkdir "%APPDATA%\Claude" 2>nul
      type nul > "%APPDATA%\Claude\claude_desktop_config.json"
      ```
    </CodeGroup>

    After creating the file, add your configuration from the [Installation](/installation) page.
  </Accordion>

  <Accordion title="Codex startup timeout errors" icon="clock">
    If Codex shows startup timeout errors when connecting to Synta MCP:

    ### Solution

    Codex requires extended timeout settings for Synta MCP to work properly. Add these timeout configurations to your `~/.codex/config.toml` file:

    ```toml theme={null}
    [mcp_servers.synta-mcp]
    # ... your existing configuration ...
    startup_timeout_sec = 30
    tool_timeout_sec = 360
    ```

    ### Alternative: Increase Startup Timeout

    If you still see timeout errors after adding the above settings, try increasing the startup timeout:

    ```toml theme={null}
    [mcp_servers.synta-mcp]
    # ... your existing configuration ...
    startup_timeout_sec = 40
    tool_timeout_sec = 360
    ```

    ### Why This Happens

    Synta MCP performs initial setup operations when starting, which may exceed Codex's default timeout settings. The extended timeouts allow proper initialization.

    ### After Updating

    1. Save your `config.toml` file
    2. Restart your terminal or Codex session
    3. Verify with: `codex mcp list`
  </Accordion>

  <Accordion title="Connection timeout or network errors" icon="wifi">
    If you're experiencing timeouts or connection issues:

    ### Solution

    1. **Check Internet Connection**
       * Ensure you have a stable internet connection
       * Try accessing the MCP server URL in a browser

    2. **Firewall/Proxy Settings**
       * Check if your firewall is blocking the connection
       * If using a corporate proxy, ensure npx can access external URLs
       * You may need to configure proxy settings in your environment

    3. **N8N Instance Accessibility**
       * Verify your N8N instance is running and accessible
       * Test the URL in a browser: `https://your-instance/api/v1/health`
       * Check if the instance requires VPN or special network access
  </Accordion>
</AccordionGroup>

## Getting Help

If you're still experiencing issues after trying the solutions above:

<CardGroup cols="2">
  <Card title="GitHub Issues" icon="github" href="https://github.com/Synta-ai/synta-rules-for-agents/issues">
    Report bugs or request features on our GitHub repository
  </Card>

  <Card title="Community Discussions" icon="comments" href="https://github.com/Synta-ai/synta-rules-for-agents/discussions">
    Ask questions and get help from the community
  </Card>
</CardGroup>

<Card title="When Seeking Help, Include">
  1. Which AI client you're using (Cursor, Claude Desktop, Claude Code, etc.)
  2. Operating system (macOS, Windows, Linux)
  3. Node.js version (run `node --version`)
  4. Configuration file contents (with API keys redacted)
  5. Error messages or screenshots

  <div class="callout mint-my-4 mint-px-4 mint-py-3 mint-overflow-hidden mint-rounded-xl mint-flex mint-gap-3 mint-border mint-border-[#c15f3c]/30 mint-bg-[#c15f3c]/10">
    <div class="mint-mt-0.5 mint-w-4 mint-flex-shrink-0">
      <svg class="mint-w-4 mint-h-4 mint-text-[#c15f3c]" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
        <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
      </svg>
    </div>

    <div class="mint-text-sm mint-text-[#c15f3c]">
      <strong class="mint-text-[#c15f3c]">Never share your API keys or login credentials publicly.</strong> Always redact credentials when sharing configuration files or error messages.
    </div>
  </div>
</Card>