# MCP server

URLpipe speaks the Model Context Protocol, so an AI agent can fetch and read pages directly instead of you writing the HTTP calls. Point any MCP client at one endpoint and it can turn a URL into Markdown, a screenshot, metadata or a Lighthouse audit on its own.

The tools are the endpoints documented in this site — same arguments, same responses, same credits. There is nothing new to learn: if you know `POST /markdown`, you know `fetch_markdown`.

## Create a token

MCP uses its own credential: an organization token, created in [MCP access](https://urlpipe.dev/app/organization/api_tokens) under your organization. It is not the project API key the HTTP endpoints take — a project key names one project, and an agent works across all of them.

You choose what a token may do when you create it:

- **Fetch pages and read results** — everything. This is what an agent normally needs.
- **Read past results only** — can list projects, read usage and retrieve results somebody already paid for, but cannot fetch a page. A token that physically cannot spend your credits.

A token is shown once and stored as a hash, so copy it when you create it. Deleting it revokes it immediately. You can also narrow a token to a single project, or give it an expiry date.

## Connect a client

This is a remote server, so there is nothing to install and no command to run. A client needs three things, and they are the whole of the setup:

- **Transport** — streamable HTTP. The server answers each message with a single JSON response; it opens no SSE stream and keeps no session.
- **URL** — `https://urlpipe.dev/mcp`
- **Authentication** — an `Authorization: Bearer YOUR_TOKEN` header, the same one every URLpipe request uses. There is no OAuth flow to complete: set the header and the client is connected.

How you register a server differs by client — some take these values in a form, some in a command, and most keep them in a JSON file of this shape:

MCP client configuration

```
{
  "mcpServers": {
    "urlpipe": {
      "type": "http",
      "url": "https://urlpipe.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

Keep the token out of that file if the file is in version control. Many clients expand environment variables inside it — check yours.

## The tools

12 tools are the API endpoints. Each takes the same arguments its endpoint does, and answers with the same body.

Tool

Endpoint

Credits

fetch\_markdown

[POST /markdown](https://urlpipe.dev/docs/markdown)

1

fetch\_html

[POST /html](https://urlpipe.dev/docs/html)

1

capture\_screenshot

[POST /screenshot](https://urlpipe.dev/docs/screenshot)

1

capture\_pdf

[POST /pdf](https://urlpipe.dev/docs/pdf)

1

capture\_console\_errors

[POST /console](https://urlpipe.dev/docs/console)

1

run\_lighthouse\_audit

[POST /lighthouse](https://urlpipe.dev/docs/lighthouse)

2

extract\_metadata

[POST /meta](https://urlpipe.dev/docs/meta)

1

detect\_technologies

[POST /technologies](https://urlpipe.dev/docs/technologies)

1

extract\_keywords

[POST /keywords](https://urlpipe.dev/docs/keywords)

15

summarize\_page

[POST /summarize](https://urlpipe.dev/docs/summarize)

17

extract\_data

[POST /extract](https://urlpipe.dev/docs/extract)

24

scrape\_url

[POST /scrape](https://urlpipe.dev/docs/scrape)

per operation

5 more exist only here, because an organization token reaches more than one project and the HTTP API's credential does not:

Tool

What it does

list\_projects

Your projects and their ids. Every other tool needs one.

get\_usage

Credits used and remaining, when they reset, and what each operation costs.

get\_result

The result of an earlier call, by its token. Free.

list\_requests

What a project has already fetched, newest first, with each token. Filters by labels.

get\_request

One request in detail: timings, options, outcome, webhook delivery.

### Arguments

Every endpoint tool takes `project_id` and `url`, plus the optional arguments its endpoint accepts.

- **Name**
  : `project_id`
  **Type**
  : integer
  **Required**
  : Required
  **Description**
  : Which project the request belongs to — it is recorded and billed against that project. Get it from `list_projects`. This is the one argument the HTTP endpoints don't have.
- **Name**
  : `url`
  **Type**
  : string
  **Required**
  : Required
  **Description**
  : The page to fetch. A public http(s) URL.
- **Name**
  : `sync`
  **Type**
  : boolean
  **Description**
  : Wait for the result and return it. Defaults to `false`, exactly as the API does — see [async & sync modes](https://urlpipe.dev/docs/async).
- **Name**
  : `max_age`
  **Type**
  : string
  **Description**
  : How fresh a stored result must be to be reused. Defaults to 7 days — see [caching & freshness](https://urlpipe.dev/docs/caching).
- **Name**
  : `residential`
  **Type**
  : boolean
  **Description**
  : Fetch the page from a home-ISP address instead of a datacentre one. See [residential exits](https://urlpipe.dev/docs/residential).
- **Name**
  : `report_to`
  **Type**
  : string
  **Description**
  : Async only: where to deliver the result. Defaults to the project's configured endpoint. Webhooks behave exactly as they do over HTTP.
- **Name**
  : `labels`
  **Type**
  : object
  **Description**
  : Your own keys to find the request by later, e.g. `{"client": "acme"}`. They come back in the metadata and in `list_requests`, which filters by them. See [labels](https://urlpipe.dev/docs/labels).
- **Name**
  : `idempotency_key`
  **Type**
  : string
  **Description**
  : Makes the call safe to retry: the same key within 24 hours returns the first call's token and result instead of new work. The `Idempotency-Key` header, as an argument — see [retries & duplicates](https://urlpipe.dev/docs/retries#idempotency-key).

## Prompts and resources

Besides the tools, the server offers ready-made prompts — in Claude Code they appear as `/mcp__urlpipe__<name>` commands. Each tells the agent which tools to call and what to report; the calls it makes are billed as usual.

- `read_page` — Read a URL as Markdown, with its JavaScript run, and answer a question about it. 1 credit.
- `audit_page` — A health report for one URL: Lighthouse scores and Core Web Vitals, console errors, and a screenshot checked for anything broken. 4 credits.
- `compare_pages` — Two URLs side by side: what each says, how each presents itself (title, description, Open Graph image) and where they differ. 4 credits.

And one resource, `urlpipe://pricing`: URLpipe's plans and what each operation costs in credits, including when a call is free (a cached result, a failed fetch). Read it before a large run.

## Async is still the default

As with the HTTP API, a call returns a token straight away and the work continues in the background. Pass `sync: true` when you want the agent to wait and be handed the result; otherwise it collects the result with `get_result`.

An async call also delivers to the project's webhook if one is configured, and a sync call does not — the same rule, and the same reason, as over HTTP: a sync caller already has the answer in hand. See [async & sync modes](https://urlpipe.dev/docs/async).

## What it costs

An MCP call spends exactly what the matching endpoint spends, from the same monthly allowance — there is no separate meter and no surcharge for using an agent. Reused results are free, and a failed fetch is never billed. The [credits page](https://urlpipe.dev/docs/credits) has the full table; `get_usage` returns your live numbers and the same prices, so an agent can check what a run will cost before it starts.

Worth telling an agent once: `fetch_markdown` costs 1 credit and `summarize_page` costs 17. If the agent is going to read the page itself anyway, Markdown is both cheaper and the better input — reach for the AI operations when the summary or the keyword list is the thing you are producing.

## Errors and limits

A refused call comes back as a tool error whose body is the API's own error object — the same `error` code and message an HTTP caller gets, so `quota_exceeded`, `concurrency_limit` and `invalid_url` mean what [the errors page](https://urlpipe.dev/docs/errors) says they mean.

The endpoint is rate limited per token, at a ceiling comfortably above one call per second sustained. Your plan's parallel-request limit applies here too.

Source: https://urlpipe.dev/docs/mcp