Sixpence MCP Server

An MCP (Model Context Protocol) server that provides fallback web page fetching capabilities when standard methods fail. This server wraps an API that uses a distributed browser network with real human IPs to bypass common blocks and fetch difficult-to-access content.

Quick Start

1. Get an API key from Sixpence
2. Install the server: npm install -g sixpence-mcp
3. Add to Claude Desktop config:

{
  "mcpServers": {
    "sixpence": {
      "command": "npx",
      "args": ["sixpence-mcp"],
      "env": {
        "SIXPENCE_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. Restart Claude Desktop

Overview

This MCP server provides a priority fallback for fetching actual webpage content when standard methods fail.

Key Difference from Web Search

• This tool: Gets the ACTUAL PAGE CONTENT (full HTML, text, data)
• Web search: Only gets search result summaries and snippets

When to Use This Tool (PRIORITY USE CASES)

Use fetch_webpage IMMEDIATELY when:

• web_fetch returns ANY error (403, "Failed to fetch", blocked, etc.)
• You need the actual content of a specific page (not search results)
• The user asks you to read, analyze, or extract data from a specific URL
• You encounter Cloudflare protection or bot detection
• Sites return empty content or block AI agents

Common Scenarios

• Reading news articles or blog posts
• Analyzing specific product pages
• Extracting data from protected sites
• Accessing JavaScript-rendered content
• Bypassing geo-restrictions or IP blocks

Features

• Fetch HTML content from web pages
• Uses distributed browser network with real human IPs
• Bypasses common bot detection and blocking mechanisms
• Handles JavaScript-rendered content
• Optionally extract href links from pages
• Built-in error handling and timeout management

Installation

Prerequisites

• Node.js 16 or higher
• npm or yarn package manager
• Claude Desktop application

Option 1: Install from npm (Recommended)

npm install -g sixpence-mcp

Or using npx (no installation required):

npx sixpence-mcp

Option 2: Install from Source

1. Clone this repository:

git clone https://github.com/0xJomo/sixpence-mcp.git
cd sixpence-mcp

2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

4. (Optional) Link globally for testing:

npm link

Configuration

The server requires an API key and can be configured using environment variables:

• SIXPENCE_API_KEY: Your API key for authentication (required)
• SIXPENCE_API_BASE_URL: API base URL (optional, defaults to https://api.sixpence.ai)

Getting an API Key

Contact Sixpence (https://sixpence.ai) to obtain an API key for the web inspection service.

Setting Environment Variables

You can set environment variables in several ways:

Option 1: Direct in Claude Desktop Config (Recommended)

See the Claude Desktop integration section below.

Option 2: System Environment Variables

macOS/Linux:

export SIXPENCE_API_KEY="your-api-key-here"
export SIXPENCE_API_BASE_URL="https://your-api.com"

Windows:

set SIXPENCE_API_KEY=your-api-key-here
set SIXPENCE_API_BASE_URL=https://your-api.com

Option 3: .env File (for development)

Create a .env file in the project root:

SIXPENCE_API_KEY=your-api-key-here
# Optional: Custom base URL
# SIXPENCE_API_BASE_URL=https://your-api.com

Claude Desktop Integration

Step 1: Locate Configuration File

Find your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Step 2: Add Server Configuration

Add the following to your claude_desktop_config.json:

If installed via npm:

{
  "mcpServers": {
    "sixpence": {
      "command": "npx",
      "args": ["sixpence-mcp"],
      "env": {
        "SIXPENCE_API_KEY": "your-api-key-here"
      }
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "sixpence": {
      "command": "node",
      "args": ["/absolute/path/to/sixpence-mcp/dist/index.js"],
      "env": {
        "SIXPENCE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Note: For source installation, replace /absolute/path/to/sixpence-mcp with the actual path where you cloned this repository.

Step 3: Restart Claude Desktop

Completely quit and restart Claude Desktop for the changes to take effect.

Step 4: Verify Installation

In a new Claude conversation, you can verify the tool is available by asking: "What MCP tools do you have available?" or "Can you use the fetch_webpage tool?"

Usage Guide

IMPORTANT: Tool Selection Priority

When a user asks to read/analyze a specific webpage:

1. First attempt: web_fetch
2. If ANY error occurs: IMMEDIATELY use fetch_webpage (NOT web search!)
3. Only use web search if the user wants to find pages, not read a specific one

Why This Matters

• Users asking for specific page content want THE ACTUAL PAGE, not search results about it
• This tool succeeds where others fail due to Sixpence's distributed browser network
• Web search gives summaries; this tool gives full content

Automatic Usage Examples

Good - Immediate fallback:

User: Can you read this article: https://protected-news-site.com/article
Claude: I'll fetch that article for you.
[web_fetch fails with 403]
Claude: I'll use the Sixpence fetch tool to access that protected page.
[Uses fetch_webpage - SUCCESS]

Bad - Wrong fallback:

User: Can you read this article: https://protected-news-site.com/article  
Claude: I'll fetch that article for you.
[web_fetch fails with 403]
Claude: Let me search for information about that article.
[Uses web search - WRONG! User wanted the actual article, not search results]

When to Explicitly Request This Tool

You can guide Claude to use this tool in these scenarios:

1. Known problematic sites:

   "This site usually blocks bots, can you fetch it anyway?"

2. After standard fetch fails:

   "If you can't fetch it normally, try alternative methods"

3. Direct request:

   "Use the fetch_webpage tool to get content from https://example.com"

Tool Parameters

The fetch_webpage tool accepts:

• url (required): The URL to fetch
• showHrefLinks (optional): Boolean to extract all href links from the page (default: false)
  • Set to true when you need to analyze site navigation or find linked pages
  • Useful for crawling, site mapping, or finding related content
• apiKey (optional): API key if not set via environment variable

Example Claude Interactions

Implicit usage:

User: Can you get the content from https://protected-site.com?
Claude: I'll fetch that page for you.
[If standard fetch fails, automatically uses fetch_webpage]

Explicit usage:

User: Use fetch_webpage to get https://blocked-site.com
Claude: I'll use the distributed browser network tool to fetch that page.

Extracting links:

User: Can you find all the links on https://example.com?
Claude: I'll fetch the page and extract all the links for you.
[Uses fetch_webpage with showHrefLinks: true]

Response Format

The tool returns the webpage content as a JSON object containing the page data. Claude will process this and present the relevant information to you.

Decision Flowchart for AI Assistants

User requests specific URL content?
├─ YES: Try web_fetch first
│   └─ Did it fail? (403, blocked, etc.)
│       ├─ YES → Use fetch_webpage IMMEDIATELY ✓
│       └─ NO → Success, use the content
│
└─ NO: User asking to "find" information?
    └─ YES → Use web search

REMEMBER: fetch_webpage > web search when you need actual page content!

Error Handling

The server provides detailed error messages for various scenarios:

• Invalid API Key: "Invalid API key" (401 error)
• Rate Limiting: "Rate limit exceeded. Please try again later." (429 error)
• Timeouts: Default 30-second timeout with clear timeout messages
• Network Errors: Specific messages for connection refused, DNS resolution failures, etc.
• Invalid API Endpoint: Detects when HTML is returned instead of JSON (incorrect endpoint)
• API Errors: Detailed error messages from the backend service

Development

Available Scripts

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Run in development mode with auto-reload
npm run dev

# Run type checking
npm run type-check

Testing with MCP Inspector

The MCP Inspector is a useful tool for testing your server:

# Set your API key first
export SIXPENCE_API_KEY="your-api-key-here"

# Run the inspector
npx @modelcontextprotocol/inspector node dist/index.js

In the inspector, you can:

1. See available tools
2. Test the fetch_webpage tool with different URLs
3. View request/response details

Troubleshooting

Common Issues

1. "API key must be provided"

   • Ensure SIXPENCE_API_KEY is set in your Claude Desktop config
   • Verify the API key is valid and active

2. "Cannot resolve API endpoint domain"

   • Check your internet connection
   • Verify the API base URL is correct
   • Default base URL: https://api.sixpence.ai

3. "API returned HTML instead of expected Map"

   • This usually means the API endpoint is incorrect
   • Verify you're using the correct endpoint URL

4. Timeout errors

   • Some pages take longer to load
   • Default timeout is 30 seconds
   • Complex JavaScript sites may timeout

5. Tool not appearing in Claude

   • Ensure you've restarted Claude Desktop after configuration
   • Check the configuration file path is correct
   • Verify the absolute path to dist/index.js is correct

Debug Mode

To see debug output, run the server manually:

export SIXPENCE_API_KEY="your-api-key"
node /path/to/sixpence-mcp/dist/index.js

This will show:

• Server start confirmation
• API base URL being used
• Whether API key is set

Advanced Configuration

Multiple API Endpoints

You can configure multiple instances with different API keys or endpoints:

{
  "mcpServers": {
    "sixpence-primary": {
      "command": "npx",
      "args": ["sixpence-mcp"],
      "env": {
        "SIXPENCE_API_KEY": "primary-api-key",
        "SIXPENCE_API_BASE_URL": "https://api1.example.com"
      }
    },
    "sixpence-backup": {
      "command": "npx",
      "args": ["sixpence-mcp"],
      "env": {
        "SIXPENCE_API_KEY": "backup-api-key",
        "SIXPENCE_API_BASE_URL": "https://api2.example.com"
      }
    }
  }
}

Custom Timeout

While the timeout is currently hardcoded to 30 seconds, you can modify this in the source code if needed.

API Details

Backend API Format

The server constructs API endpoints by combining the base URL with tool-specific paths:

• Base URL: https://api.sixpence.ai (or custom via SIXPENCE_API_BASE_URL)
• fetch_webpage tool endpoint: {baseUrl}/request_page

The API expects:

• POST requests with JSON body containing url and optional showHrefLinks
• x-api-key header for authentication
• Returns JSON response with structure:

  {
    "success": true,
    "taskResult": {
      "page": "<page content>"
    }
  }

Changelog

v1.3.0 (Latest)

• Rebranded to Sixpence MCP
• Changed environment variables to SIXPENCE_API_KEY and SIXPENCE_API_BASE_URL
• Restructured API to use base URL + tool-specific endpoints
• Enhanced tool description to prioritize usage over web search
• Added explicit decision flowchart for AI assistants
• Improved documentation with clear fallback guidance

v1.2.0

• Updated to accept single URL instead of array
• Changed response format to match new API structure
• Added showHrefLinks parameter support
• Improved error detection for invalid endpoints
• Consolidated documentation

v1.1.1 (2025-01-28)

• Fixed HTML response validation
• Enhanced network error messages

v1.1.0

• Initial release with fetch_webpage tool

License

MIT

Support

For issues or questions, please open an issue in the repository.