Fetch MCP Server Guide for API Integration

Fetch MCP Server Guide for API Integration

Modern frontier language models possess deep reasoning capabilities but operate against static knowledge cutoffs. The Fetch Model Context Protocol (MCP) server bridges this limitation by granting autonomous agents on-demand HTTP and HTTPS retrieval capabilities. Developed as part of the official Model Context Protocol reference suite, the Fetch MCP server translates raw web pages, documentation portals, and REST API payloads into sanitized, token-efficient Markdown representations optimized for agent context windows.

Rather than dumping raw HTML filled with scripts, tracking pixels, and CSS styles into your inference stream, the Fetch server processes web content through an HTML-to-Markdown normalization pipeline. It strips irrelevant DOM nodes, isolates substantive prose, enforces pagination caps, and respects HTTP transport protocols.

1. Problem Statement and Architecture

When LLMs attempt to interact with the broader internet, naive HTTP scraping presents three fundamental obstacles:

1. ▸Context Window Exhaustion: A single enterprise landing page or API reference page frequently contains tens of thousands of lines of boilerplate HTML, navigation banners, tracking scripts, and stylesheets. Feeding this raw payload into an agent burns thousands of tokens while polluting prompt attention.
2. ▸Missing Native Protocol Adapters: LLM hosts like Claude Desktop, Cursor, and OpenAI Codex CLI run locally inside user workstations and sandboxed developer environments. They lack built-in socket managers or HTTP clients capable of streaming responses into tool-call workflows without host-level code execution.
3. ▸Encoding and Redirection Fragility: Web endpoints return varied character sets, gzip-compressed streams, recursive HTTP redirects, and varying HTTP status codes.

+-----------------------------------------------------------------------------------+
|                              Client Architecture                                  |
|                                                                                   |
|  +--------------------+        JSON-RPC 2.0 (stdio)        +-------------------+  |
|  |  Claude / Cursor   | <================================> |  mcp-server-fetch |  |
|  +--------------------+                                    +---------+---------+  |
+----------------------------------------------------------------------|------------+
                                                                       |
                                                              HTTP GET | User-Agent
                                                                       v
                                                             +-------------------+
                                                             |   Target Server   |
                                                             |  (Docs / REST API)|
                                                             +-------------------+

The Fetch MCP server solves these challenges by implementing an out-of-process Python stdio daemon powered by httpx and readability-lxml. When the host agent issues a tool invocation, the Fetch daemon executes the network request, follows standard redirects, extracts substantive readable content, converts the document into GitHub Flavored Markdown, and returns the structured string payload directly across the stdio transport.

2. Prerequisites and Environment Matrix

The official Fetch server is distributed through PyPI under the package name mcp-server-fetch. It requires Python 3.10 or higher. Running the server via Astral's uvx runner provides instant, isolated virtual environment execution without global dependency pollution.

Verify that uvx is accessible in your system terminal before configuring your client:

uvx --version

If uv is not installed, install it via the official standalone script:

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Multi-Host Configuration Snippets

The Fetch server communicates over standard input/output (stdio). Below are production-tested configuration snippets for the three leading developer hosts.

Claude Desktop

Place this entry in your claude_desktop_config.json:

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

Cursor IDE

Add the server definition to your workspace .cursor/mcp.json or global user configuration:

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

OpenAI Codex CLI

In your OpenAI Codex configuration (~/.codex/config.toml):

[mcp_servers.fetch]
command = "uvx"
args = ["mcp-server-fetch"]

4. Step-by-Step Tool Discovery and Invocation

Upon server initialization, the client negotiates capabilities and requests available tools using JSON-RPC 2.0.

Tool Registration

The server registers the fetch tool with schema parameters controlling document truncation and offset pagination:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "fetch",
        "description": "Fetches a URL from the internet and extracts its contents as markdown.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "description": "URL to fetch"
            },
            "max_length": {
              "type": "integer",
              "description": "Maximum number of characters to return",
              "default": 5000
            },
            "start_index": {
              "type": "integer",
              "description": "Character index offset for pagination",
              "default": 0
            },
            "raw": {
              "type": "boolean",
              "description": "Return raw content instead of parsed markdown",
              "default": false
            }
          },
          "required": ["url"]
        }
      }
    ]
  }
}

Tool Invocation Wire Frame

When the user asks: "Fetch the official Model Context Protocol architecture documentation from example.com/docs", the host transmits the following JSON-RPC tool call:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "fetch",
    "arguments": {
      "url": "https://example.com/docs/architecture",
      "max_length": 4000,
      "raw": false
    }
  }
}

The daemon fetches the URL, converts the main article container into clean Markdown, and responds:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Architecture Overview\n\nThe Model Context Protocol (MCP) standardizes how applications provide context to LLMs...\n\n- Transport: JSON-RPC 2.0 over stdio or SSE.\n- Roles: Hosts, Clients, and Servers."
      }
    ],
    "isError": false
  }
}

5. Common Errors and Production Troubleshooting

1. spawn uvx ENOENT Error

• ▸Symptom: Claude Desktop or Cursor logs Error: spawn uvx ENOENT when launching the server.
• ▸Root Cause: Desktop GUI applications do not inherit shell profile configurations (.zshrc, .bashrc) where uv was appended to $PATH.
• ▸Solution: Provide the absolute path to the uvx executable in the config file. On macOS and Linux, locate the path via which uvx (commonly ~/.local/bin/uvx or /usr/local/bin/uvx). On Windows PowerShell, run Get-Command uvx (commonly C:\Users\<USER>\.cargo\bin\uvx.exe or C:\Users\<USER>\AppData\Local\Programs\uv\uvx.exe).

{
  "mcpServers": {
    "fetch": {
      "command": "/Users/developer/.local/bin/uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

2. HTTP 403 Forbidden / Cloudflare Bot Challenges

• ▸Symptom: Fetching public pages returns 403 Forbidden or a Cloudflare Turnstile challenge page.
• ▸Root Cause: mcp-server-fetch transmits a standard Python httpx User-Agent string. Anti-bot Web Application Firewalls (WAFs) reject unrecognized automated user agents.
• ▸Solution: For heavily guarded dynamic single-page applications or Cloudflare-protected portals, employ the Puppeteer MCP Server, which runs a headless Chromium browser instance with full JavaScript execution and human-like fingerprinting.

3. Response Truncation on Extensive Documents

• ▸Symptom: Content cuts off abruptly in the middle of long API specifications.
• ▸Root Cause: The default max_length parameter caps responses at 5,000 characters to safeguard the model's context window.
• ▸Solution: Instruct your agent to paginate through large documentation sets using the start_index parameter, or increase max_length up to 20,000 when working with expansive context models.

6. External Citations and Security Guardrails

When granting web access to autonomous agents, adhere to strict operational security guidelines:

1. ▸Local Network Protection: Ensure the Fetch server is restricted from calling internal RFC-1918 private subnets (10.0.0.0/8, 192.168.0.0/16, 127.0.0.1) to prevent Server-Side Request Forgery (SSRF) against internal microservices.
2. ▸Verified Registry Artifacts: Only install the official Python package from PyPI. Review release notes and cryptographic hashes before running production workloads.

• ▸PyPI mcp-server-fetch Package (opens in a new tab)
• ▸Model Context Protocol GitHub Servers Repository (opens in a new tab)
• ▸Official Model Context Protocol Specification (opens in a new tab)