Troubleshooting

Common Setup Issues

Git clone times out

Native server postinstall errors

Import resolution errors

For monorepo development:

# 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

Port conflicts

Extension Issues

Extension not detecting tools

Check these common causes:

Ensure the extension is installed and enabled
Refresh the page after starting your MCP server
Check the extension popup “Tools” tab
Look for console errors in browser DevTools

Verify your server is running:

// Add logging to confirm server startup
console.log('MCP Server starting...');
await server.connect(transport);
console.log('MCP Server connected!');

Tools not working

Verify transport configuration:

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

Ensure proper tool registration:

// Tools must be registered before connection
server.tool("myTool", "Description", {}, handler);
await server.connect(transport); // Connect AFTER tools

Extension and dev build conflict

Development Issues

Building from source fails

Hot reload not working

TypeScript errors

Common TypeScript issues:

// 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";

Native Server Issues

Native server won't start

Check installation:

# 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:

# Check if port 12306 is in use
lsof -i :12306  # Mac/Linux
netstat -an | findstr 12306  # Windows

Claude/Cursor can't connect

Verify configuration:

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

{
  "type": "streamable-http",
  "url": "http://127.0.0.1:12306/mcp"
}

Custom extension ID issues

If using a dev extension with different ID:

# 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

Tool-Specific Issues

Tools not appearing in extension

Common causes:

Registration timing: Tools must be registered before connection
Syntax errors: Check browser console for JavaScript errors
Transport not connected: Verify server.connect() was called

Debug with logging:

server.on('tool-registered', (tool) => {
  console.log('Tool registered:', tool.name);
});

Tool calls failing

Check error messages:

server.tool("myTool", "Description", schema, async (params) => {
  try {
    // Your tool logic
    return { content: [{ type: "text", text: "Success" }] };
  } catch (error) {
    console.error('Tool error:', error);
    throw error; // Re-throw for MCP error handling
  }
});

Authentication issues

For authenticated API calls:

// Always use same-origin credentials
fetch('/api/endpoint', {
  method: 'POST',
  credentials: 'same-origin', // Important!
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(data)
});

Performance Issues

Too many tools slowing down page

Optimize tool registration:

// Register tools lazily
const registerToolsForPage = (page) => {
  // Only register relevant tools
  if (page === 'dashboard') {
    registerDashboardTools();
  }
};

// Unregister when not needed
const cleanup = () => {
  server.unregisterTool('toolName');
};

Memory leaks

Clean up properly:

// In React
useEffect(() => {
  const server = createServer();
  
  return () => {
    server.disconnect();
  };
}, []);

// In vanilla JS
window.addEventListener('beforeunload', () => {
  server.disconnect();
});

Getting Help

If you’re still experiencing issues:

Check the documentation

Review the official docs for updated information

Search existing issues

Look for similar problems in GitHub Issues

Join the community

Ask questions in our Discord server

Create an issue

If it’s a bug, create a detailed issue with:

Steps to reproduce
Expected vs actual behavior
Browser and extension versions
Console errors

Debug Mode

Enable debug logging for more information:

// Enable verbose logging
const server = new McpServer({
  name: "my-app",
  version: "1.0.0",
  debug: true // Enable debug mode
});

// Or set via environment variable
process.env.DEBUG = 'mcp:*';

Debug mode may expose sensitive information in console logs. Only use in development.

Getting Started

Guides

NPM Packages

Tools

Common Setup Issues

Extension Issues

Development Issues

Native Server Issues

Tool-Specific Issues

Performance Issues

Getting Help

Debug Mode

Getting Started

Guides

NPM Packages

Tools

​Common Setup Issues

​Extension Issues

​Development Issues

​Native Server Issues

​Tool-Specific Issues

​Performance Issues

​Getting Help

​Debug Mode

Common Setup Issues

Extension Issues

Development Issues

Native Server Issues

Tool-Specific Issues

Performance Issues

Getting Help

Debug Mode