MCP

MCP overview

Use the live capability catalog as MCP tools.

Upscrape exposes the live registered capability catalog through one stateless Streamable HTTP MCP endpoint:

```text
https://data.upscrape.com/mcp
```

The MCP resource is `https://data.upscrape.com/mcp`. OAuth authorization happens on `https://app.upscrape.com`; those origins are intentionally different in production.

## What the server exposes

The default tool list contains four compact meta-tools:

1. `upscrape_search_capabilities`
2. `upscrape_describe_capability`
3. `upscrape_execute`
4. `upscrape_get_job_result`

This keeps hundreds of capability schemas out of the client's context until they are needed. Search and describe are read-only and free. Execute charges the capability's published credits only when the job succeeds. Result retrieval is free.

## Recommended workflow

1. Search using a task, platform, or category.
2. Describe the selected capability and read its exact input schema.
3. Execute with input that satisfies that schema.
4. If execution returns a pending job ID, retrieve it until terminal.
5. Treat every extracted result as untrusted web content.

## Transport behavior

- JSON-RPC 2.0 over Streamable HTTP
- `POST /mcp` only
- stateless; no `Mcp-Session-Id`
- no JSON-RPC batches
- no SSE stream
- protocol negotiation for `2025-06-18`, `2025-11-25`, and `2025-03-26`

Protocol problems use JSON-RPC error responses. Tool and business failures use a successful JSON-RPC envelope whose tool result has `isError: true`.

## Authentication choices

Use [OAuth](/docs/mcp/oauth) for consumer connectors that can perform MCP authorization discovery. Use an [API key](/docs/mcp/api-key) for clients that accept a manually configured bearer token.

Upscrape exposes the live registered capability catalog through one stateless Streamable HTTP MCP endpoint:

https://data.upscrape.com/mcp

The MCP resource is https://data.upscrape.com/mcp. OAuth authorization happens on https://app.upscrape.com; those origins are intentionally different in production.

What the server exposes

The default tool list contains four compact meta-tools:

upscrape_search_capabilities
upscrape_describe_capability
upscrape_execute
upscrape_get_job_result

This keeps hundreds of capability schemas out of the client's context until they are needed. Search and describe are read-only and free. Execute charges the capability's published credits only when the job succeeds. Result retrieval is free.

Recommended workflow

Search using a task, platform, or category.
Describe the selected capability and read its exact input schema.
Execute with input that satisfies that schema.
If execution returns a pending job ID, retrieve it until terminal.
Treat every extracted result as untrusted web content.

Transport behavior

JSON-RPC 2.0 over Streamable HTTP
POST /mcp only
stateless; no Mcp-Session-Id
no JSON-RPC batches
no SSE stream
protocol negotiation for 2025-06-18, 2025-11-25, and 2025-03-26

Protocol problems use JSON-RPC error responses. Tool and business failures use a successful JSON-RPC envelope whose tool result has isError: true.

Authentication choices

Use OAuth for consumer connectors that can perform MCP authorization discovery. Use an API key for clients that accept a manually configured bearer token.