> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-b-sync-npm-packages-docs-bf03420.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Troubleshooting guide for WebMCP setup issues, tool registration errors, native host connection problems, extension detection, and debugging MCP client connections.

## Common Setup Issues

<AccordionGroup>
  <Accordion title="Git clone times out">
    If the initial clone fails, complete it manually:

    ```bash theme={null}
    git clone https://github.com/WebMCP-org/npm-packages.git
    cd npm-packages
    git pull origin main
    ```
  </Accordion>

  <Accordion title="Native server postinstall errors">
    These errors during `pnpm install` are normal and can be ignored:

    ```
    Cannot find module '/path/to/apps/native-server/dist/scripts/postinstall.js'
    ```

    The packages will still build correctly.
  </Accordion>

  <Accordion title="Import resolution errors">
    For monorepo development:

    ```bash theme={null}
    # Ensure the workspace is properly built:
    pnpm build:shared  # Build internal shared packages
    pnpm build:apps    # Build all applications

    # Or run from the root with workspace support:
    pnpm dev
    ```
  </Accordion>

  <Accordion title="Port conflicts">
    Default ports used by WebMCP:

    * Main dev server: 5173-5174
    * Extension dev server: 3000
    * Native host: 12306

    Change ports if conflicts occur with your existing services.
  </Accordion>
</AccordionGroup>

## Extension Issues

<AccordionGroup>
  <Accordion title="Extension not detecting tools">
    **Check these common causes:**

    1. Ensure the extension is installed and enabled
    2. Refresh the page after starting your MCP server
    3. Check the extension popup "Tools" tab
    4. Look for console errors in browser DevTools

    **Verify your server is running:**

    ```javascript theme={null}
    // Add logging to confirm server startup
    console.log('MCP Server starting...');
    await server.connect(transport);
    console.log('MCP Server connected!');
    ```
  </Accordion>

  <Accordion title="Tools not working">
    **Verify transport configuration:**

    ```javascript theme={null}
    // Check allowedOrigins includes your domain
    new TabServerTransport({
      allowedOrigins: ["*"] // Or specific domains
    })
    ```

    **Ensure proper tool registration:**

    ```javascript theme={null}
    // For navigator.modelContext approach (recommended)
    navigator.modelContext.registerTool({
      name: "myTool",
      description: "Description",
      inputSchema: { type: "object", properties: {} },
      async execute(args) {
        return { content: [{ type: "text", text: "Result" }] };
      }
    });
    ```
  </Accordion>

  <Accordion title="Extension and dev build conflict">
    If you have both the Chrome Web Store extension and a dev build:

    1. **Disable one version** to avoid port conflicts
    2. Go to `chrome://extensions/`
    3. Toggle off the version you're not using
    4. Reload your tabs
  </Accordion>
</AccordionGroup>

## Development Issues

<AccordionGroup>
  <Accordion title="Building from source fails">
    **Step-by-step fix:**

    ```bash theme={null}
    # Clean install
    rm -rf node_modules
    rm pnpm-lock.yaml

    # Reinstall
    pnpm install

    # Build shared packages first
    pnpm build:shared

    # Then build apps
    pnpm build:apps
    ```
  </Accordion>

  <Accordion title="Hot reload not working">
    For extension development with hot reload:

    ```bash theme={null}
    # Run in dev mode
    pnpm --filter @mcp-b/extension dev
    ```

    Make sure you've loaded the unpacked extension from:
    `./apps/extension/.output/chrome-mv3`
  </Accordion>

  <Accordion title="TypeScript errors">
    **Common TypeScript issues:**

    ```typescript theme={null}
    // Ensure proper imports
    import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

    // Use .js extensions for MCP SDK imports
    import { TabServerTransport } from "@mcp-b/transports";
    ```
  </Accordion>
</AccordionGroup>

## Native Server Issues

<AccordionGroup>
  <Accordion title="Native server won't start">
    **Check installation:**

    ```bash theme={null}
    # Verify global installation
    npm list -g @mcp-b/native-server

    # Reinstall if needed
    npm uninstall -g @mcp-b/native-server
    npm install -g @mcp-b/native-server
    ```

    **Check port availability:**

    ```bash theme={null}
    # Check if port 12306 is in use
    lsof -i :12306  # Mac/Linux
    netstat -an | findstr 12306  # Windows
    ```
  </Accordion>

  <Accordion title="Claude/Cursor can't connect">
    **Verify configuration:**

    1. Native server is running: `@mcp-b/native-server`
    2. Extension is active and connected
    3. Correct config in MCP client:

    ```json theme={null}
    {
      "type": "streamable-http",
      "url": "http://127.0.0.1:12306/mcp"
    }
    ```
  </Accordion>

  <Accordion title="Custom extension ID issues">
    If using a dev extension with different ID:

    ```bash theme={null}
    # Create .env file
    cp apps/native-server/.env.example apps/native-server/.env

    # Edit with your extension ID
    echo "DEV_EXTENSION_ID=your-extension-id" > apps/native-server/.env

    # Rebuild and restart
    pnpm build
    pnpm dev
    ```
  </Accordion>
</AccordionGroup>

## Tool-Specific Issues

<AccordionGroup>
  <Accordion title="Tools not appearing in extension">
    **Common causes:**

    1. **Registration timing**: Ensure `@mcp-b/global` is imported
    2. **Syntax errors**: Check browser console for JavaScript errors
    3. **Tool registration**: Verify tools are properly registered

    **Debug with logging:**

    ```javascript theme={null}
    // After registering a tool
    console.log('Tool registered');

    // Check if navigator.modelContext is available
    if ('modelContext' in navigator) {
      console.log('WebMCP is loaded');
    }
    ```
  </Accordion>

  <Accordion title="Tool calls failing">
    **Check error messages:**

    ```javascript theme={null}
    navigator.modelContext.registerTool({
      name: "myTool",
      description: "Description",
      inputSchema: { type: "object", properties: {} },
      async execute(params) {
        try {
          // Your tool logic
          return { content: [{ type: "text", text: "Success" }] };
        } catch (error) {
          console.error('Tool error:', error);
          // Return error response
          return {
            content: [{ type: "text", text: `Error: ${error.message}` }],
            isError: true
          };
        }
      }
    });
    ```
  </Accordion>

  <Accordion title="Authentication issues">
    **For authenticated API calls:**

    ```javascript theme={null}
    // Always use same-origin credentials
    fetch('/api/endpoint', {
      method: 'POST',
      credentials: 'same-origin', // Important!
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
    ```
  </Accordion>
</AccordionGroup>

## Performance Issues

<AccordionGroup>
  <Accordion title="Too many tools slowing down page">
    **Optimize tool registration:**

    ```javascript theme={null}
    // Register tools lazily based on page context
    const registerToolsForPage = (page) => {
      // Only register relevant tools
      if (page === 'dashboard') {
        const reg = navigator.modelContext.registerTool({
          name: 'dashboard_tool',
          description: 'Dashboard-specific tool',
          inputSchema: { type: "object", properties: {} },
          async execute() {
            // Tool logic
            return { content: [{ type: "text", text: "Result" }] };
          }
        });

        // Store registration for cleanup
        return reg;
      }
    };

    // Unregister when not needed
    const cleanup = (registration) => {
      registration.unregister();
    };
    ```
  </Accordion>

  <Accordion title="Memory leaks">
    **Clean up properly:**

    ```javascript theme={null}
    // In React with useWebMCP
    import { useWebMCP } from '@mcp-b/react-webmcp';

    // Auto cleanup when component unmounts
    useWebMCP({
      name: 'my_tool',
      description: 'Tool description',
      handler: async () => {
        return { success: true };
      }
    });

    // In vanilla JS
    const registration = navigator.modelContext.registerTool({
      name: 'my_tool',
      description: 'Tool description',
      inputSchema: { type: "object", properties: {} },
      async execute() {
        return { content: [{ type: "text", text: "Result" }] };
      }
    });

    // Unregister when done
    window.addEventListener('beforeunload', () => {
      registration.unregister();
    });
    ```
  </Accordion>
</AccordionGroup>

## Getting Help

If you're still experiencing issues:

<Steps>
  <Step title="Check the documentation">
    Review the [official docs](https://docs.mcp-b.ai) for updated information
  </Step>

  <Step title="Search existing issues">
    Look for similar problems in [GitHub Issues](https://github.com/WebMCP-org/npm-packages/issues)
  </Step>

  <Step title="Join the community">
    Ask questions in our [Discord server](https://discord.gg/ZnHG4csJRB)
  </Step>

  <Step title="Create an issue">
    If it's a bug, [create a detailed issue](https://github.com/WebMCP-org/npm-packages/issues/new) with:

    * Steps to reproduce
    * Expected vs actual behavior
    * Browser and extension versions
    * Console errors
  </Step>
</Steps>

## Debug Mode

Enable debug logging for more information:

```javascript theme={null}
// Check if WebMCP is loaded
if (window.__mcpBridge) {
  console.log('MCP Server:', window.__mcpBridge.server);
  console.log('Registered tools:', window.__mcpBridge.tools);
}

// Check navigator.modelContext availability
if ('modelContext' in navigator) {
  console.log('navigator.modelContext is available');
} else {
  console.error('navigator.modelContext not found - ensure @mcp-b/global is imported');
}
```

<Note>
  Debug mode may expose sensitive information in console logs. Only use in development.
</Note>