OpenHands

Set up Spicrawl in OpenHands (web UI, CLI or SDK): add the hosted MCP server with your API key, install the agent skill, and add AGENTS.md rules so the agent fetches web pages cheaply and handles errors correctly.

Three steps give OpenHands Spicrawl's tools, the knowledge to write Spicrawl code, and rules for using both well. You need an API key from app.spicrawl.com (spicrawl_live_...). The server uses a bearer key, not OAuth.

1. Add the MCP server

Go to Customize → MCP Servers, select Add custom server, and choose the SHTTP transport (the recommended one for remote servers):

Field	Value
Server name	`spicrawl`
URL	`https://mcp.spicrawl.com/mcp`
Authentication	Bearer token
API Key	your key (`spicrawl_live_...`)

OpenHands sends the token as Authorization: Bearer <key>. Select Test connection, then save. The server applies to new conversations.

The server lists 25 spicrawl_* tools. See MCP server for each tool.

Current OpenHands releases do not read MCP servers from the [mcp] section of config.toml. That format is from legacy OpenHands (V0). Add the server through the UI, the CLI or the SDK instead.

2. Install the skill

OpenHands loads skills from .agents/skills/ in the repository (preferred) or the older .openhands/skills/, and from ~/.agents/skills/ or ~/.openhands/skills/ for every project. A project skill overrides a user skill with the same name.

mkdir -p .agents/skills/spicrawl
curl -fsSL https://app.spicrawl.com/skill.md -o .agents/skills/spicrawl/SKILL.md

The skill's name must match its directory, spicrawl. The older .openhands/microagents/ directory still works but .agents/skills/ replaces it. See Agent skill.

3. Add rules to AGENTS.md

OpenHands puts the full AGENTS.md at the repository root into the initial system prompt, so keep it short. Paste this section into it:

AGENTS.md

## Web data (Spicrawl)

Use Spicrawl to read web pages: the spicrawl_* MCP tools in chat, or
POST https://api.spicrawl.com/v1/scrape with `Authorization: Bearer $SPICRAWL_API_KEY` in code.
Docs: https://docs.spicrawl.com/llms.txt (append .md to any page URL for Markdown).

- Ask for markdown: `response_format: "markdown"` (API default is html); on spicrawl_scrape, `format: "markdown"`.
- Check the site's status, not only the HTTP status: `X-Target-Status` header, or `status`
  in the JSON envelope (spicrawl_scrape with `format: "json"`). 200 is the page; 404/410
  mean it does not exist; 403/429/503 mean the site refused, so escalate.
- On an error, switch on `code`. Retry only when `retryable` is true, after
  `retry_after_seconds`. Read `diagnostics.hint` and change what it names first.
  Never retry ERR::REQUEST::*, ERR::AUTH::* or ERR::LIMIT::QUOTA_EXCEEDED.
- Escalate one step at a time and stop at the first that works:
  plain fetch (1 credit) -> `js_render: true` (3) -> add the user's own `proxy`
  if they have one. Empty or skeleton content means render; ERR::UPSTREAM::CHALLENGE
  or a 403 target status means retry once, then the user's own proxy.
- Set `max_cost` on every request to the price of the step you intend.
- Keep the cache on (default). Set `cache: false` only for prices, stock or other live data.
- Trim tokens with `main_content_only` (on by default for markdown), `include_tags`, `exclude_tags`.
- For more than 20 URLs, use a batch job (spicrawl_batch_submit / POST /v1/batch).
  Batch items return raw HTML and apply only render, proxy and block_resources settings.
- Never print or commit SPICRAWL_API_KEY. Log `X-Request-Id` for failures.

A first task to try

Start a conversation and write:

Use Spicrawl to read https://example.com/pricing as markdown. List each plan with its monthly price.
If the page comes back empty, retry with rendering.

The agent should call spicrawl_scrape with url and format: "markdown", and add render: true only if the first result is empty. For a coding task:

Add a fetch_page(url) function to this project that calls the Spicrawl API for markdown,
following the Web data rules in AGENTS.md. Read the key from SPICRAWL_API_KEY.

Compare the result with the reference implementation in Best practices.

Troubleshooting

Symptom	Fix
Test connection fails or the server returns 401	The API Key field must hold only the key (`spicrawl_live_...`), with Bearer token selected. For a custom header, the value is `Bearer` followed by the key.
The server is missing after upgrading from an older OpenHands	Servers in `config.toml` `[mcp]` are ignored. Add it again through the UI, CLI or SDK.
A new server has no tools in a running conversation	MCP changes apply to new conversations. Start a new one.
The agent writes `js_render` on `spicrawl_scrape` and gets "unknown argument"	The tool's argument is `render`. The API field is `js_render`.
Usage tools return `ERR::AUTH::INSUFFICIENT_SCOPE`	Grant the `read` scope to the key in the dashboard.