Composio + Scrapeless: Add a Custom MCP Toolkit

TL;DR:

• Scrapeless is not in Composio's toolkit catalog, so it joins as a Custom MCP toolkit. Composio's dashboard has an Add Custom MCP dialog, marked Beta, that creates one from a remote MCP server.
• The dialog takes four values. A display name, the server URL https://api.scrapeless.com/mcp, API key as the authentication type, and x-api-token as the header name under Advanced settings.
• Leave Header prefix empty. Scrapeless expects the bare key in x-api-token. With a prefix such as token, the handshake and the 25-tool listing still succeed, and every tool call fails.
• Composio checks that a key was entered, not that Scrapeless accepts it. Check the key and the header value before you add the toolkit, and confirm with one tool call afterwards.
• The toolkit belongs to one Composio project. Add its CUSTOM_ slug to a session, and pass session.mcp.url to any MCP client.
• Get a key on the Scrapeless free plan and add the toolkit in a few minutes.

Composio sessions give an agent authenticated tools across a long list of apps, with the credentials held on Composio's side. What a session does not include is the live web, such as a page as it renders today or the results of a Google search. The Scrapeless MCP server provides those as tools, and Composio's Custom MCP feature lets a session call them next to its built-in toolkits.

This guide adds Scrapeless through the dashboard dialog, then uses the toolkit in a session. Most of the work is a single form. The part that needs care is the header, because a wrong header format looks connected until a tool actually runs.

Why Scrapeless Joins Composio as a Custom MCP Toolkit

Composio's catalog holds the toolkits Composio publishes, and Scrapeless is not one of them. For a service outside the catalog, Composio's Custom MCP guide describes the route. You register a remote MCP server by its public HTTPS URL and authentication scheme, and Composio creates a toolkit with a CUSTOM_ slug, syncs the server's tools and proxies each tool call to the server with the connected account's credentials.

Three limits come with it. Custom MCP is experimental, and Composio says its setup flow and contracts may change. The toolkit is scoped to the Composio project that registers it. And Composio does not host the server, so the server must be reachable over HTTPS; Scrapeless is a hosted endpoint, so nothing runs on your machine.

The same guide still describes registration as API-only and lists dashboard management as coming soon. The Composio dashboard in September 2026 already showed an Add Custom MCP dialog, labelled Beta and MCP Only, and that dialog is the route this guide follows. The API route is covered in the FAQ.

What Scrapeless Adds to a Composio Session

The server exposes 25 tools, grouped by job:

• scrape_markdown, scrape_html and scrape_screenshot return a rendered page as Markdown, raw HTML or an image in one call.
• Sixteen browser_* tools, from browser_create and browser_goto to browser_click, browser_type and browser_snapshot, drive a cloud browser session step by step.
• crawl_start, crawl_result and crawl_cancel run a crawl in the background and collect it later.
• google_search and google_trends return search results and trend data, and ai_scraper captures answers from AI assistants such as ChatGPT, Gemini and Perplexity.

All 25 arrive as one toolkit. In a default session, Composio's guide says an agent discovers custom tools through its tool search and runs them through the Tool Router, the same way it reaches built-in toolkits.

Prerequisites

• A Composio account with a project. Custom MCP toolkits belong to one project.
• A Scrapeless API key from the Scrapeless dashboard. A key that serves only Composio can be rotated without touching your other integrations.
• Python 3 for the check in Step 1, which uses only the standard library.
• For Step 4, the Composio Python SDK (this guide used composio 0.21.1) and your Composio project API key. Step 4's session code has not yet been run against a Composio project for this guide.

Step 1: Check the Key and the Header Value

Composio's guide lists a known gap worth planning around: when you connect an API-key server, setup checks that a key was provided, not that the remote server accepts it. Scrapeless adds a second blind spot, because it answers the MCP handshake and lists its tools for any key value. A wrong key or a wrong header format shows up only when a tool runs.

This script sends the requests an MCP client sends, with the key in the x-api-token header, lists the tools and then calls scrape_markdown once. It follows the MCP streamable HTTP transport, JSON-RPC over POST to a single endpoint, and needs nothing beyond the Python standard library:

import json
import os
import urllib.request

URL = "https://api.scrapeless.com/mcp"
PREFIX = os.environ.get("HEADER_PREFIX", "")
HEADERS = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "x-api-token": f"{PREFIX} {os.environ['SCRAPELESS_API_KEY']}".strip(),
}


def post(payload, session_id=None):
    headers = dict(HEADERS)
    if session_id:
        headers["Mcp-Session-Id"] = session_id
    request = urllib.request.Request(URL, data=json.dumps(payload).encode(), headers=headers)
    with urllib.request.urlopen(request, timeout=120) as response:
        body = response.read().decode()
        session_id = response.headers.get("Mcp-Session-Id") or session_id
    events = [line[5:].strip() for line in body.splitlines() if line.startswith("data:")]
    return session_id, json.loads(events[-1]) if events else None


session, init = post({
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {"protocolVersion": "2025-06-18", "capabilities": {},
               "clientInfo": {"name": "header-check", "version": "1.0"}},
})
post({"jsonrpc": "2.0", "method": "notifications/initialized"}, session)
_, listing = post({"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, session)
_, result = post({
    "jsonrpc": "2.0", "id": 3, "method": "tools/call",
    "params": {"name": "scrape_markdown", "arguments": {"url": "https://example.com"}},
}, session)

server = init["result"]["serverInfo"]
text = "".join(part.get("text", "") for part in result["result"]["content"])
print(server["name"], server["version"])
print("tools listed:", len(listing["result"]["tools"]))
if text.startswith("Failed to fetch data"):
    print("key rejected:", text[:20])
else:
    print(f"key accepted: {len(text)} characters of Markdown")

With your key exported as SCRAPELESS_API_KEY, it prints:

scrapeless-mcp-server 0.2.0
tools listed: 25
key accepted: 184 characters of Markdown

Now export HEADER_PREFIX=token and run it again. The script puts token and a space in front of the key, the shape a prefixed header value takes:

scrapeless-mcp-server 0.2.0
tools listed: 25
key rejected: Failed to fetch data

The handshake and the tool count are identical in both runs. Only the tool call tells them apart, and Bearer as the prefix fails the same way.

Step 2: Add Scrapeless With Add Custom MCP

In the Composio dashboard, open Add Custom MCP, the dialog titled "Create a toolkit from a remote MCP server", and fill it in:

Then choose Add.

Header prefix is the field to watch. It exists for APIs that expect a scheme word in front of the credential, such as Bearer. Scrapeless reads the whole x-api-token value as the key, so any prefix turns a valid key into one it rejects, as the second run in Step 1 showed.

Get these settings right before you save. In Composio's API the header format is part of the toolkit's authentication scheme, and the Custom MCP guide says the server URL and the authentication scheme cannot change after registration; an attempt returns 409 Conflict. To fix a toolkit saved with a prefix, use Delete on its page and add it again. Deleting a custom toolkit also removes its auth configs and connected accounts, so you connect the account again afterwards.

Setting this up now? The Scrapeless free plan covers the connection and your first tool calls.

Step 3: Connect an Account and Let the Tools Sync

An API-key toolkit has nothing to call until an account is connected, and this is where the key goes. The empty Header prefix from Step 2 only means that nothing is placed in front of the key. Connecting opens a page titled "Composio wants to connect to your" followed by the toolkit's name, with a single required API Key field. Paste your Scrapeless API key there and choose Connect Account. Composio stores the key on the connected account and places it in the x-api-token header of every request it sends to Scrapeless.

The first sync starts in the background once that account becomes active. Back on the Scrapeless page, Connected Accounts lists the account as Active, and Available actions shows 25, one for each Scrapeless tool, under names such as "Ai scraper" and "Browser click". Later connections do not sync the toolkit again, so when Scrapeless adds tools, use Sync on that page. A custom toolkit holds at most 500 tools.

A synced tool list proves Composio reached the server. It does not prove the key, for the reason Step 1 showed, which is why the last step ends in a tool call.

The key now also lives with a third party. The OWASP secrets management guidance treats rotation as routine, and a key dedicated to Composio is one you can rotate without breaking anything else.

Step 4: Use the Toolkit in a Session

Add the toolkit's slug to a session. With mcp=True, the session also exposes a hosted MCP server that any MCP client can use.

Note: this code follows the Composio Python SDK 0.21.1 and Composio's session guides; it has not yet been run against a Composio project for this guide. It needs COMPOSIO_API_KEY set to your project API key.

from composio import Composio

composio = Composio()  # reads COMPOSIO_API_KEY from the environment

session = composio.sessions.create(
    user_id="user_123",
    toolkits=["CUSTOM_SCRAPELESS"],
    connected_accounts={"CUSTOM_SCRAPELESS": ["ca_your_connected_account_id"]},
    mcp=True,
)

print(session.mcp.url)

Use the slug shown on your toolkit page if it differs from CUSTOM_SCRAPELESS; Composio adds the CUSTOM_ prefix when it registers the toolkit. The connected_accounts entry pins the account the calls run as. Sessions match accounts by user_id on their own only when the toolkit's auth config has tool-router matching enabled, and without it calls fail with NoActiveConnection. Pinning the account works either way.

Composio's guide to sessions over MCP passes session.mcp.url and session.mcp.headers to the client's MCP configuration, for frameworks such as the OpenAI Agents SDK and the Claude Agent SDK. The headers carry the credential for that URL, so hand them to the client without logging them.

Then give the agent one checkable job:

Use the Scrapeless scrape_markdown tool to fetch https://example.com
and reply with the first heading of the returned page, quoted exactly.

A working setup answers with "# Example Domain". A reply that quotes Failed to fetch data points back to the key or the header prefix.

Fix the Common Problems

For more on what the server exposes, read the Scrapeless MCP server announcement. The Browser MCP documentation carries the configuration reference, the Scraping API page covers the actors behind the tools, and pricing lists what a call costs.

Conclusion

Adding Scrapeless to Composio takes one dialog: a display name, https://api.scrapeless.com/mcp, API key authentication, x-api-token as the header name and an empty header prefix. Connect an account with your key, let the tools sync, and add the CUSTOM_ toolkit to a session.

What needs care is the gap between synced and working. Composio confirms that a key was entered, and Scrapeless lists its tools for any key, so a prefix mistake passes both checks. Run the key check before you add the toolkit and one real tool call after it, and the setup is proven end to end.

Ready to give your Composio agents a live view of the web? Start with the Scrapeless free plan and add the toolkit.

FAQ

Q: Can I add a custom MCP server to Composio?

Yes. Custom MCP registers a remote server by its HTTPS URL and authentication scheme and turns it into a project-scoped toolkit with a CUSTOM_ slug. The dashboard has an Add Custom MCP dialog for it, and Composio's API offers the same registration through its custom toolkit endpoints.

Q: What goes in Header prefix for Scrapeless?

Nothing. Set the header name to x-api-token and leave the prefix empty, because Scrapeless reads the whole header value as the key. A token or Bearer prefix makes every tool call fail even though the tools still sync.

Q: Where do I enter the Scrapeless API key in Composio?

On the connect page, when you connect an account on the toolkit. The Add Custom MCP dialog only defines the header name and prefix; the connect page asks for the API Key, and Composio sends that value as the x-api-token header.

Q: Why do my Scrapeless tools sync in Composio but every call fails?

Tool listing works with any key value, so a synced toolkit does not prove the credential. Calls that return Failed to fetch data mean the header value is wrong: a filled-in Header prefix or an invalid key. Run the check from Step 1 with your key to see which.

Q: Can I change the header settings after adding the toolkit?

Not in place. Composio treats the server URL and the authentication scheme as fixed after registration. Delete the toolkit, add it again with the right settings, and connect the account again, since deletion removes its connections.

Q: Can I register Scrapeless through Composio's API instead of the dashboard?

Yes. POST /api/v3.1/custom/toolkits/upsert takes the server URL and an API_KEY authentication scheme with a headers object. Composio allows header names other than Authorization as long as one header value contains {{generic_api_key}}, so the entry for Scrapeless is "x-api-token": "{{generic_api_key}}". For API-key servers, the guide adds a separate auth config step before accounts can connect.

Q: Is the Scrapeless toolkit available in all my Composio projects?

No. A Custom MCP toolkit is scoped to the project that registers it. Add Scrapeless in each project that needs it.

Q: Can Claude, Cursor or another MCP client use Scrapeless through Composio?

Yes. Create a session with mcp=True and give the client session.mcp.url and session.mcp.headers. The client then reaches the Scrapeless tools through the Composio session.

Q: How many tools does Scrapeless add to Composio?

25: three scrape_* tools, sixteen browser_* tools, three crawl_* tools, plus google_search, google_trends and ai_scraper.