WebMCP Documentation - AI-Powered Web Tools

Unlock Desktop AI Integration: The native host is a core feature that bridges your browser’s WebMCP tools to desktop AI assistants. Use browser-based tools directly from Claude Code, Claude Desktop, or any MCP-compatible client!

The native host bridges your browser’s WebMCP tools to local MCP clients like Claude Code and Claude Desktop. This allows AI assistants running on your desktop to interact with tools you’ve registered on your websites.

Prerequisites:

MCP-B Chrome Extension installed from Chrome Web Store
Node.js 18+ installed
A website with WebMCP tools registered

How It Works

The native host acts as a proxy server that:

Runs locally on your machine (default port: 12306)
Communicates with the MCP-B Chrome extension
Exposes browser tools to desktop MCP clients via HTTP
Respects your browser’s authentication (cookies, sessions)

Installation

Step 1: Install the Native Server

Install the native server globally via npm:

npm
pnpm
yarn

npm install -g @mcp-b/native-server

The native server must be installed globally to make the @mcp-b/native-server command available system-wide.

Step 2: Verify Installation

Check that the installation was successful:

# Check if command is available
which @mcp-b/native-server  # Mac/Linux
where @mcp-b/native-server  # Windows

# Check installed version
npm list -g @mcp-b/native-server

Starting the Native Host

Basic Usage

Start the native server with default settings:

@mcp-b/native-server

You should see output like:

Native host server running on http://127.0.0.1:12306
Extension connected: daohopfhkdelnpemnhlekblhnikhdhfa
Ready to accept MCP client connections

Keep this terminal window open while using the native host. Closing it will stop the server.

Configuration Options

The native server supports several configuration options:

Custom Port
Verbose Logging
Multiple Options

@mcp-b/native-server --port 8080

Running as a Background Service

For continuous use, you can run the native server as a background service.

Mac/Linux (pm2)
Windows (NSSM)

# Install pm2
npm install -g pm2

# Start as service
pm2 start @mcp-b/native-server --name mcp-native-host

# Set to auto-start on boot
pm2 startup
pm2 save

# Check status
pm2 status

# View logs
pm2 logs mcp-native-host

Connecting to Claude Code

Claude Code is Anthropic’s command-line AI assistant that supports MCP.

Step 1: Configure Claude Code

Add the native host to your Claude Code MCP configuration:

Mac/Linux
Windows

Edit ~/.config/claude/mcp.json:

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

Step 2: Start Claude Code

Start Claude Code in your project directory:

cd your-project
claude

Step 3: Verify Connection

Once Claude Code starts, ask it to list available tools:

You: What MCP tools are available?

You should see tools from any websites you have open with the MCP-B extension active.

Open your website in Chrome with the MCP-B extension enabled before asking Claude Code to use tools. The native host can only access tools from active browser tabs.

Connecting to Claude Desktop

Claude Desktop is Anthropic’s desktop application that supports MCP.

Step 1: Configure Claude Desktop

Add the native host to Claude Desktop’s MCP settings:

Mac
Windows

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Step 2: Restart Claude Desktop

Restart Claude Desktop to load the new configuration:

Quit Claude Desktop completely
Reopen Claude Desktop
Wait a few seconds for MCP connections to initialize

Step 3: Test the Connection

In Claude Desktop, ask about available tools:

What tools can you access from my browser?

Claude should list tools from your open browser tabs.

Verifying the Setup

Check Native Host Status

Verify the native host is running and accepting connections:

Browser Test
MCP Inspector

curl http://127.0.0.1:12306/health

Expected response:

{
  "status": "ok",
  "extensionConnected": true,
  "version": "1.0.0"
}

Check Extension Connection

Verify the MCP-B extension is connected:

Open Chrome and click the MCP-B extension icon
Go to the “Settings” tab
Check for “Native Host: Connected” status
If disconnected, ensure the native server is running

Test Tool Execution

Try calling a tool from your MCP client:

Open a website with WebMCP tools

Navigate to a site with tools registered (e.g., the MCP-B demo)

Ask Claude to use a tool

In Claude Code or Claude Desktop:

Use the available tools to show me what you can do on this website

Verify execution

Check that Claude successfully calls the tool
Verify the tool executes in the browser tab
Confirm Claude receives the tool’s response

Debugging Issues

Native Server Won’t Start

Port already in use

Error: EADDRINUSE: address already in use :::12306Solution: Another process is using port 12306

# Find the process using the port
lsof -i :12306  # Mac/Linux
netstat -ano | findstr :12306  # Windows

# Kill the process or use a different port
@mcp-b/native-server --port 12307

Command not found

Error: @mcp-b/native-server: command not foundSolution: Global npm modules not in PATH

# Find npm global bin directory
npm config get prefix

# Add to PATH (Mac/Linux)
export PATH="$PATH:$(npm config get prefix)/bin"

# Or reinstall
npm uninstall -g @mcp-b/native-server
npm install -g @mcp-b/native-server

Extension not connecting

Error: Extension not connected in server logsSolution: Extension ID mismatch or extension not installed

Verify the MCP-B extension is installed from the Chrome Web Store
Check the extension is enabled at chrome://extensions/
Restart Chrome
Restart the native server

MCP Client Can’t Connect

Connection refused

Error: ECONNREFUSED when Claude tries to connectChecklist:

Native server is running: curl http://127.0.0.1:12306/health
Port matches config: Check both server and client config
Firewall not blocking: Allow localhost connections
Config file is valid JSON: Validate with a JSON linter

No tools available

Issue: Claude connects but can’t see any toolsChecklist:

Browser tabs with WebMCP tools are open
MCP-B extension is active (click icon to check)
Tools are registered: Check extension “Tools” tab
Native server is connected to extension: Check server logs

# Enable verbose logging to debug
@mcp-b/native-server --verbose

Tools fail to execute

Issue: Claude sees tools but execution failsDebug steps:

Check browser console for errors:
- Open DevTools (F12)
- Look for errors when tool is called
Check native server logs:
```
@mcp-b/native-server --verbose
```
Verify tab is still active:
- If you closed or navigated away from the tab, tools won’t work
- Tools are scoped to specific pages
Test directly in extension:
- Click MCP-B extension icon
- Go to “Tools” tab
- Manually call the tool
- Check for errors in extension popup

Configuration Issues

Config file not found

Issue: Claude can’t find the MCP configuration fileSolution: Create the directory structure

Claude Code (Mac/Linux)
Claude Code (Windows)
Claude Desktop (Mac)

mkdir -p ~/.config/claude
echo '{"mcpServers":{}}' > ~/.config/claude/mcp.json

Invalid JSON syntax

Error: Claude fails to load configSolution: Validate your JSON

# Validate JSON syntax (Mac/Linux)
cat ~/.config/claude/mcp.json | python -m json.tool

# Common issues:
# - Missing commas between entries
# - Trailing commas (not allowed in JSON)
# - Unquoted keys or values
# - Incorrect URL format

Correct format:

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

Wrong URL format

Issue: Connection fails due to incorrect URLCorrect formats:

✅ http://127.0.0.1:12306/mcp
✅ http://localhost:12306/mcp
❌ http://127.0.0.1:12306 (missing /mcp path)
❌ https://127.0.0.1:12306/mcp (https not supported)
❌ ws://127.0.0.1:12306/mcp (wrong protocol)

Security Considerations

The native host provides access to browser tools that can perform actions on your behalf. Only use it on trusted networks and with tools you control.

Best Practices

Localhost Only

The native host should only listen on localhost (127.0.0.1), not on external network interfaces. This is the default behavior.Avoid:

# Don't expose to network
@mcp-b/native-server --host 0.0.0.0

Firewall Configuration

Ensure your firewall allows localhost connections but blocks external access:

Allow: 127.0.0.1:12306 → localhost only
Block: 0.0.0.0:12306 → all interfaces

Tool Permissions

Only expose tools that you would be comfortable executing through your browser’s UI. Tools have the same permissions as your browser session.Review tools carefully:

Check what data they can access
Verify what actions they can perform
Ensure proper authentication checks

Monitor Tool Usage

Keep the native server logs visible or check them regularly to monitor tool execution:

@mcp-b/native-server --verbose

Watch for:

Unexpected tool calls
Failed authentication attempts
Unusual patterns of usage

Advanced Usage

Multiple Extension Support

If you’re testing with both the Chrome Web Store extension and a development build:

Disable one version to avoid port conflicts. Both versions will try to connect to the same native host.

Go to chrome://extensions/
Disable the version you’re not using
Restart Chrome
Restart the native server

Custom Extension IDs

For development builds with custom extension IDs, configure the native server:

# Set via environment variable
EXTENSION_ID=your-dev-extension-id @mcp-b/native-server

# Or create a config file
echo '{"extensionId":"your-dev-extension-id"}' > ~/.mcp-native-host/config.json
@mcp-b/native-server --config ~/.mcp-native-host/config.json

Monitoring and Logging

Enable detailed logging for debugging:

Console Logging
File Logging
JSON Logging

@mcp-b/native-server --verbose --log-level debug

Health Monitoring

Monitor the native host health with automated checks:

#!/bin/bash
# health-check.sh

# Check if server is responding
if curl -sf http://127.0.0.1:12306/health > /dev/null; then
  echo "✓ Native host is healthy"
  exit 0
else
  echo "✗ Native host is not responding"
  exit 1
fi

Next Steps

Claude Code Integration

Deep dive into using Claude Code with WebMCP

Development Guide

Learn how to develop WebMCP tools

Examples

Explore complete examples and patterns

Troubleshooting

Getting Help

If you encounter issues not covered here:

Check server logs

Run with verbose logging: @mcp-b/native-server --verbose

Test health endpoint

Verify server is running: curl http://127.0.0.1:12306/health

Check GitHub Issues

Search for similar problems: WebMCP Issues

Join Discord

Ask the community: WebMCP Discord

When reporting issues, include:

Native server version (npm list -g @mcp-b/native-server)
MCP-B extension version
Operating system and version
MCP client (Claude Code/Desktop) and version
Relevant log output with --verbose flag

Getting Started

Core Features

Architecture & Development

​How It Works

​Installation

​Step 1: Install the Native Server

​Step 2: Verify Installation

​Starting the Native Host

​Basic Usage

​Configuration Options

​Running as a Background Service

​Connecting to Claude Code

​Step 1: Configure Claude Code

​Step 2: Start Claude Code

​Step 3: Verify Connection

​Connecting to Claude Desktop

​Step 1: Configure Claude Desktop

​Step 2: Restart Claude Desktop

​Step 3: Test the Connection

​Verifying the Setup

​Check Native Host Status

​Check Extension Connection

​Test Tool Execution

​Debugging Issues

​Native Server Won’t Start

​MCP Client Can’t Connect

​Configuration Issues

​Security Considerations

​Best Practices

​Advanced Usage

​Multiple Extension Support

​Custom Extension IDs

​Monitoring and Logging

​Health Monitoring

​Next Steps

Claude Code Integration

Development Guide

Examples

Troubleshooting

​Getting Help

How It Works

Installation

Step 1: Install the Native Server

Step 2: Verify Installation

Starting the Native Host

Basic Usage

Configuration Options

Running as a Background Service

Connecting to Claude Code

Step 1: Configure Claude Code

Step 2: Start Claude Code

Step 3: Verify Connection

Connecting to Claude Desktop

Step 1: Configure Claude Desktop

Step 2: Restart Claude Desktop

Step 3: Test the Connection

Verifying the Setup

Check Native Host Status

Check Extension Connection

Test Tool Execution

Debugging Issues

Native Server Won’t Start

MCP Client Can’t Connect

Configuration Issues

Security Considerations

Best Practices

Advanced Usage

Multiple Extension Support

Custom Extension IDs

Monitoring and Logging

Health Monitoring

Next Steps

Getting Help