# AI app builders

> Connect Spicrawl's hosted MCP server to Replit Agent, v0, Lovable and Bolt so the builder can read web pages, and call the Spicrawl API from the app it builds.

Source: https://docs.spicrawl.com/agents/app-builders

Two separate things can use Spicrawl in a prompt-to-app builder:

* **The builder's agent** reads web pages while it works (docs, competitor sites, content to copy). You connect the hosted MCP server, `https://mcp.spicrawl.com/mcp`, to the builder. It exposes 25 `spicrawl_*` tools. See [MCP server](https://docs.spicrawl.com/agents/mcp.md).
* **The app it builds** fetches pages at runtime. It calls `POST https://api.spicrawl.com/v1/scrape` from a server route. See [Calling Spicrawl from the app you build](#calling-spicrawl-from-the-app-you-build).

The MCP server authenticates with `Authorization: Bearer <your Spicrawl API key>`. It does not support OAuth, so a builder that only offers OAuth for custom servers cannot connect. Unauthenticated requests get `401 Unauthorized: send your Spicrawl API key`.

> **Warning:** Paste your key only into the builder's credential fields and secrets store, never into a chat prompt or generated source code. Keys look like `spicrawl_live_...`.

## Connect the MCP server

**Replit Agent**

Replit authenticates custom MCP servers with custom headers (or OAuth dynamic client registration, which Spicrawl does not use).

**Step 1: Open the install link**

Go to `https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6IlNwaWNyYXdsIiwiYmFzZVVybCI6Imh0dHBzOi8vbWNwLnNwaWNyYXdsLmNvbS9tY3AifQ==`. It pre-fills the name `Spicrawl` and the URL `https://mcp.spicrawl.com/mcp`. It carries no key.

**Step 2: Add the header**

Define one header: name `Authorization`, value `Bearer <your Spicrawl API key>`. Then authorize the connection in the Project Editor.

The link is the base64 encoding of this JSON. `displayName` and `baseUrl` (an HTTPS endpoint) are required, `headers` is optional:

```json
{
  "displayName": "Spicrawl",
  "baseUrl": "https://mcp.spicrawl.com/mcp"
}
```

Replit can also carry the header inside the link (`"headers": [{ "key": "Authorization", "value": "Bearer ..." }]`). Do not share or save a link built that way: anyone who opens it gets your key. Build the link without a header, as above, and type the key in after install.

To use Spicrawl from the built app, add `SPICRAWL_API_KEY` as a Replit Secret: **Tools → Secrets → New Secret**. Secrets are exposed to your code as environment variables (`process.env.SPICRAWL_API_KEY`).

**v0**

Open the &#x2A;*+** menu in the prompt form and select **MCPs**. v0 offers four authentication methods for a custom server: No Auth, Custom Headers, Bearer Token and OAuth.

1. Enter the server URL `https://mcp.spicrawl.com/mcp`.
2. Choose **Bearer Token** and paste your Spicrawl API key. Alternatively choose **Custom Headers** with header `Authorization` and value `Bearer <your Spicrawl API key>`.

To use Spicrawl from the built app, add `SPICRAWL_API_KEY` as an environment variable on the v0 project: **Project menu → Settings → Environment Variables**. Project variables are shared by every chat in the project, and v0 can use them in the code it generates.

**Lovable**

Open the **Connectors*&#x2A; dashboard, select &#x2A;*+** in the top right and choose **MCP server**. Fill in:

* **Server name**: `Spicrawl`
* **Server URL**: `https://mcp.spicrawl.com/mcp`
* **Connection type**: Direct connection

Lovable defaults to OAuth. Spicrawl has no OAuth, so switch the authentication to the bearer token or API key option (offered "for servers that don't support OAuth"), paste your Spicrawl API key, and select **Add & authorize**. Custom MCP servers are available on all plans.

Lovable's docs say custom MCP servers only give Lovable context in the project chat. They cannot power features of a published app. For the app itself, call the Spicrawl API from a backend function with the key stored as a secret, as described below.

> **Note:** Lovable's docs say "bearer token or API key" without saying which header carries an API key. If the connection returns `401`, pick the bearer token option, which sends `Authorization: Bearer <key>`.

**Bolt**

From the Bolt homepage chatbox, select the plus icon, then **Connectors → Manage connectors → Custom MCP server**. Fill in:

* **Name**: `Spicrawl`
* **URL**: `https://mcp.spicrawl.com/mcp`
* **Transport type**: `HTTP`, the standard option. Spicrawl's server is Streamable HTTP, so do not choose `SSE`.
* **Authentication**: `API key`, with your Spicrawl API key. Do not choose `MCP OAuth`.

A `Connected` status appears in the upper-right corner when it works.

> **Warning:** Bolt's docs do not say which header the `API key` option sends. Spicrawl accepts only `Authorization: Bearer <key>`. If Bolt shows an authorization error, the connector is not sending that header and cannot connect to Spicrawl yet. Use another builder above, or scrape from the app you build.

Bolt's docs describe connectors as giving Bolt access while you build. They do not say a connector is available to the running app, so give the app its key as a project secret instead.

Check the connection by asking the builder: "Use Spicrawl to read [https://example.com/pricing](https://example.com/pricing) as markdown and list each plan with its monthly price." The agent should call `spicrawl_scrape`. If it does not have the tools, or the connector reports `401`, the key is missing or wrong.

## Calling Spicrawl from the app you build

The app calls the scrape API from a server route, with the key read from the platform's secrets or environment variables as `SPICRAWL_API_KEY`. The browser calls your route, never Spicrawl.

```ts title="app/api/read/route.ts"
export async function POST(req: Request) {
  const { url } = await req.json();

  const res = await fetch("https://api.spicrawl.com/v1/scrape", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SPICRAWL_API_KEY}`,
      "Content-Type": "application/json",
    },
    // max_cost: refuse anything above a plain fetch (1 credit) before it runs.
    body: JSON.stringify({ url, response_format: "markdown", max_cost: 1 }),
  });

  if (!res.ok) {
    // Spicrawl error bodies carry a `code`; failed requests cost 0 credits.
    return Response.json(await res.json(), { status: res.status });
  }

  return Response.json({
    targetStatus: Number(res.headers.get("X-Target-Status")),
    markdown: await res.text(),
  });
}
```

Details the generated code must get right:

* `response_format` defaults to `html`. Send `"markdown"` for text you can pass to a model or render.
* A `200` from Spicrawl means Spicrawl fetched the page. The site's own status is the `X-Target-Status` header, so check it before trusting the content.
* `max_cost: 1` caps each request at a plain fetch. A page that needs JavaScript rendering (3 credits) is refused with `ERR::LIMIT::MAX_COST_EXCEEDED` at 0 credits; raise the cap and add `js_render: true` only for those pages.
* The route spends your credits on any URL it is sent. Put it behind your app's sign-in, or rate-limit it, before you publish the app.

Prompt to give the builder:

```text
Add a server route that fetches a URL through Spicrawl and returns it as markdown.
Call POST https://api.spicrawl.com/v1/scrape with the JSON body
{"url": <the URL>, "response_format": "markdown", "max_cost": 1} and the header
Authorization: Bearer followed by process.env.SPICRAWL_API_KEY.
Read the key only on the server from the environment variable SPICRAWL_API_KEY, never
in client components, never in the browser bundle, and never hard-coded.
Return the X-Target-Status response header alongside the markdown.
If Spicrawl responds with an error, pass its JSON error body and status back to the caller.
Only signed-in users may call the route.
Add a form that posts a URL to this route and shows the markdown.
```

Then add `SPICRAWL_API_KEY` in the builder's secrets or environment settings (see each tab above) before you run the app. For Next.js, do not prefix the name with `NEXT_PUBLIC_`: that would put the key in the browser bundle.

## Next steps

* [Quickstart](https://docs.spicrawl.com/quickstart.md): the full scrape request and response.
* [Errors](https://docs.spicrawl.com/errors.md): every `code` and what to do about it.
* [Best practices](https://docs.spicrawl.com/agents/best-practices.md): retries, escalation and cost limits for agent-written code.
* [MCP server](https://docs.spicrawl.com/agents/mcp.md): the 25 `spicrawl_*` tools.