Groundlane

English | 繁體中文

The trusted web access layer for AI agents.

Groundlane is an open-source, vendor-neutral remote MCP server for giving AI agents controlled access to the public web. It presents one stable interface for search, retrieval, and deterministic extraction, routes search to replaceable providers, and escalates difficult Markdown reads through an optional Jina Reader before using an isolated local or Browserless browser.

Why Groundlane?

• Model neutral: connect any Streamable HTTP MCP client instead of depending on a model vendor's built-in web tool.

• Provider neutral: route across search APIs with recurring monthly free allowances behind one normalized result contract.

• HTTP first, browser when necessary: keep ordinary reads fast and reserve Chromium for JavaScript, wait conditions, and supported fallback signals.

• Deterministic extraction: select fields with CSS selectors and receive structured JSON without an implicit LLM step.

• Security first: authenticate the MCP endpoint and apply URL, redirect, network, deadline, byte, output, and concurrency limits.

• Self-controlled deployment: run the control plane and browser workload in your own environment, including Cloudflare Workers and Containers.

Related MCP server: agentfetch

MVP tools

Browser automation is an internal implementation detail called Groundlane Browser. Groundlane does not expose persistent browser sessions in the MVP.

Quick start

Prerequisites

• Node.js 22 or newer

• pnpm 10

• Chromium for browser fallback

• At least one supported monthly-free search provider key if you want to use web_search (Tavily, Exa, Parallel, Browserbase, Brave, Firecrawl, or SerpApi)

Run locally

Clone this repository, then run:

pnpm install
pnpm exec playwright install chromium
cp .env.example .env
set -a
source .env
set +a
pnpm dev

Set a strong GROUNDLANE_AUTH_TOKEN in .env. Add one or more supported provider keys to enable search. The local server listens on the configured PORT and serves:

• POST /mcp — authenticated Streamable HTTP MCP endpoint

• GET /healthz — process liveness

• GET /readyz — Container reachability and service configuration readiness

Connect an MCP client

Configure a Streamable HTTP MCP client with the server URL and bearer token. Client configuration shapes differ, but the connection values are:

URL: http://localhost:8080/mcp
Authorization: Bearer <GROUNDLANE_AUTH_TOKEN>

Never put the token in a query string or commit it to source control.

With the server running, open another shell, load the same .env, and verify the MCP handshake and public HTTP path:

set -a
source .env
set +a
pnpm smoke

Set GROUNDLANE_SMOKE_BROWSER=1 to include the browser path.

Configuration

Groundlane reads configuration from environment variables. See .env.example for a complete local template.

Missing search credentials do not prevent web_fetch or web_extract from working. They do make the corresponding search provider unavailable.

Monthly budgets count attempted provider requests, including retryable failures, and prevent a running Groundlane instance from selecting a provider after its configured cap. They are deliberately conservative, but they are not billing truth: Containers restart, multiple instances do not share counters, and some providers charge variable credits. Keep provider-side spend limits enabled and override the budgets for your actual plans.

Architecture

MCP client
    |
    v
Cloudflare Worker / Node HTTP edge
    |  authentication, limits, request identity
    v
tool registry
    |-- web_search  -> monthly-free provider router (7 adapters)
    |-- web_fetch   -> safe HTTP -> optional Jina Reader -> browser fallback
    `-- web_extract -> fetch pipeline -> deterministic DOM extraction

Core policies and contracts do not depend on a provider or browser runtime. Adapters sit behind narrow interfaces. The browser backend can be Container-local Playwright or Browserless /content; engine and backend output fields disclose which path produced a result without changing the public MCP tools. Hosted backends receive the requested public URL, so they are opt-in rather than silent defaults.

Read Architecture for component boundaries, request flow, and design decisions.

Security

Web retrieval is an SSRF-sensitive capability. Groundlane treats user URLs, redirects, browser subresources, and search-provider URLs as untrusted. Deployments should keep authentication enabled, use an outbound network policy, and retain the default resource limits.

The project does not promise universal CAPTCHA solving, invisible automation, or access to content you are not authorized to retrieve. Operators are responsible for target-site terms, robots policies, privacy obligations, and applicable law.

See SECURITY.md for the security model and private vulnerability reporting process.

Deployment

The intended production topology uses a Cloudflare Worker as the public control plane and a Cloudflare Container for the Node/Playwright browser workload. For prerequisites, secrets, deployment steps, and verification, see Deploying on Cloudflare.

Roadmap

• Define the vendor-neutral web_fetch, web_search, and deterministic web_extract surface

• Add opt-in Jina Reader and Browserless retrieval backends with provenance

• Stabilize MCP contracts and publish compatibility fixtures

• Harden Cloudflare Worker + Container deployment and operational telemetry

• Add cache adapters and provider health/cost-aware routing

• Add opt-in batch/crawl primitives with explicit budgets

• Evaluate stateful browser sessions as a separate, lifecycle-safe capability

The roadmap is directional, not a release commitment. See the research archive for the evidence behind the current scope.

Documentation

• Architecture

• MVP product requirements

• Cloudflare deployment

• Security policy

• Contributing

• Research archive

Contributing

Issues and pull requests are welcome. Before contributing, read CONTRIBUTING.md and the Code of Conduct. Security vulnerabilities must be reported privately as described in SECURITY.md.

License

Groundlane is licensed under the Apache License 2.0.