# MCP server (/api/mcp)

The DeepScout MCP server gives AI agents the same functions as the API. An agent can add a website, read the sample data, scrape a catalog, match products and get the export files. You write what you want in plain language, and the agent calls the API for you.

The server follows the authenticated remote [MCP specification](https://modelcontextprotocol.io/specification). DeepScout hosts it, so you install nothing. Clients that support remote MCP servers connect directly. Other clients connect through the [`mcp-remote`](https://github.com/geelen/mcp-remote) module.

```txt title="Server URL"
https://mcp.deepscout.ai/mcp
```

## Setup [#setup]

### General [#general]

The server uses the Streamable HTTP transport. The sign-in uses OAuth 2.1 with dynamic client registration:

1. Add the server URL to your client.
2. Start the sign-in in the client. The client opens the [DeepScout Console](https://console.deepscout.ai) in your browser.
3. Sign in with Google or GitHub. Your first sign-in creates your account.
4. Read the name of the app and click **Approve**.

The app gets an API key with the scope **All my projects**. The key does not expire. You can see the app and disconnect it in the console, under **Settings → API keys → Connected apps**.

You can also send your own API key in the `Authorization` header and skip the sign-in. See [Use an API key](#use-an-api-key).

### Claude Code [#claude-code]

```bash
claude mcp add --transport http deepscout https://mcp.deepscout.ai/mcp
```

Start a Claude Code session and run `/mcp`. Select **deepscout**, then **Authenticate**.

### Claude [#claude]

In [claude.ai](https://claude.ai) or in Claude Desktop, open **Settings → Connectors** and click **Add custom connector**. Enter the name `DeepScout` and the server URL. Then click **Connect** to sign in.

In a Team or Enterprise organization, an owner adds the connector for the organization first. Then each member connects with their own DeepScout account.

### Codex [#codex]

Codex keeps one configuration for the CLI and the IDE extension. Add the server:

```bash
codex mcp add deepscout --url https://mcp.deepscout.ai/mcp
```

If Codex does not open the sign-in, run `codex mcp login deepscout`.

You can also add the server to `~/.codex/config.toml`:

```toml title="~/.codex/config.toml"
[mcp_servers.deepscout]
url = "https://mcp.deepscout.ai/mcp"
```

### Cursor [#cursor]

Add the server to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in your project:

```json title="mcp.json"
{
  "mcpServers": {
    "deepscout": {
      "url": "https://mcp.deepscout.ai/mcp"
    }
  }
}
```

Open **Cursor Settings → MCP** and click **Connect** next to **deepscout**.

### Visual Studio Code [#visual-studio-code]

Add the server to `.vscode/mcp.json` in your workspace:

```json title=".vscode/mcp.json"
{
  "servers": {
    "deepscout": {
      "type": "http",
      "url": "https://mcp.deepscout.ai/mcp"
    }
  }
}
```

Click **Start** above the server in the file. VS Code opens the sign-in.

### Other clients [#other-clients]

If your client supports remote MCP servers, give it the server URL. If it supports only local (stdio) servers, use `mcp-remote` with these settings:

- **Command**: `npx`
- **Arguments**: `-y mcp-remote https://mcp.deepscout.ai/mcp`
- **Environment**: none

```json
{
  "mcpServers": {
    "deepscout": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.deepscout.ai/mcp"]
    }
  }
}
```

`mcp-remote` needs Node.js 18 or later.

## Tools [#tools]

Each tool is one step of the API. The tools call the API as you, with the key of the client. So they see the same projects and get the same errors as your requests.

| Tool | What it does | API |
| --- | --- | --- |
| `scout_list_projects` | Lists your projects and the customer that pays for each one. | [`GET /projects`](/api/reference/projects/list-projects.md) |
| `scout_list_websites` | Lists the websites of a project, each with its current job and `full_scrape_estimate`. | [`GET /websites`](/api/reference/websites/list-websites.md) |
| `scout_analyze_website` | Adds a website to a project. The setup job analyzes it and scrapes free sample products. | [`POST /jobs/setup`](/api/add-website.md) |
| `scout_get_job` | Reads a setup, scraping or matching job: status, progress, estimate and charge. | [`GET /jobs/{kind}/{job_id}`](/api/jobs.md) |
| `scout_get_sample` | Gives a temporary URL of the sample products of a website. | [`GET /samples/{website_id}`](/api/sample-data.md) |
| `scout_scrape_website` | Creates a scraping job for the full catalog or for a list of product URLs. | [`POST /jobs/scraping`](/api/full-scrape.md) |
| `scout_get_url_results` | Gives a temporary URL of the CSV file with the result of each URL of a URL scrape. | [`GET /jobs/scraping/{job_id}/url-results`](/api/url-scrape.md) |
| `scout_match_websites` | Creates a matching job, or the free matching sample of the project. | [`POST /jobs/matching`](/api/matching.md) |
| `scout_approve_job` | Approves a scraping or matching job. **This charges your credit.** | [`POST /jobs/{kind}/{job_id}/approve`](/api/full-scrape.md#3-approve-the-quote) |
| `scout_list_exports` | Lists the export files of a project. | [`GET /exports`](/api/exports.md) |
| `scout_get_export` | Gives a temporary URL of one export file. | [`GET /exports/{dataset}/url`](/api/exports.md) |
| `scout_get_balance` | Reads the credit of a customer: the total, the held part and the spendable part. | [`GET /customers/{customer_id}/billing/balance`](/api/credits.md#read-the-balance) |

The tools that only read data (`scout_list_*`, `scout_get_*`) have the MCP annotation `readOnlyHint`. You can let your client run them without a prompt. The other tools create or approve jobs. They do not remove or overwrite data.

The server also gives the agent the order of the steps and the usual duration of each job. A scrape of 100,000 products can take one day. The agent knows this and does not report a slow job as a problem.

Sample data, the matching sample and most website analyses are free. A scrape or a matching costs the same as through the API. See [Pricing](/api/pricing.md).

<Callout type="warn" title="Approvals use your credit">
Only `scout_approve_job` charges your credit. The server tells the agent to show you the price and to wait for your answer before it approves a job. Keep the confirmation prompt of your client on for this tool.
</Callout>

## Example prompts [#example-prompts]

Copy a prompt into your client and change the values in brackets. Each prompt names the data that the agent needs, so the agent asks fewer questions.

<Accordions type="single">
<Accordion title="Add a competitor and check the sample">

**Use case**

Add a new website to a project and see if DeepScout reads its product data correctly before you pay for a scrape.

**Prompt**

> Add `[https://www.example-shop.cz]` to my DeepScout project `[Default project]`. The market is `[CZ]` and the currency is `[CZK]`. Wait until the setup job is complete. Then download the sample and tell me which fields are often empty or look wrong. Do not start a paid scrape.

</Accordion>
<Accordion title="Scrape the full catalog after a quote">

**Use case**

Scrape the full catalog of a website that has a completed setup, with a price that you approve first.

**Prompt**

> In my DeepScout project `[Default project]`, create a full scrape of `[example-shop.cz]`. Show me the price estimate and the maximum charge, and wait for my approval. After I approve, follow the job until it is complete. Then give me the export files of this website.

</Accordion>
<Accordion title="Update prices for a list of products">

**Use case**

Get the current prices of some products only, for example the products of a promotion, without a scrape of the full catalog.

**Prompt**

> Scrape only these product URLs on `[example-shop.cz]` in my DeepScout project `[Default project]`. Show me the price and wait for my approval. When the job is complete, read the URL results. Tell me which URLs gave no product, and the reason for each one.
>
> URLs: `[paste the product URLs]`

</Accordion>
<Accordion title="Match my products with competitors">

**Use case**

Find your products on the websites of your competitors. Look at the free matching sample first, then decide about the full matching.

**Prompt**

> In my DeepScout project `[Default project]`, `[my-shop.cz]` is my website and `[competitor-a.cz, competitor-b.cz]` are my competitors. Run the free matching sample first. When it is complete, show me 10 matched pairs from the export. Then create the full matching, show me the price and wait for my approval.

</Accordion>
<Accordion title="Compare my prices with the market">

**Use case**

Make a price report from the matches export, when your client can run code or read files.

**Prompt**

> Get the matches export of my DeepScout project `[Default project]` and the product export of each website in it. For each of my products that has at least one competitor, compare my price with the lowest competitor price. List the 20 products with the largest difference in percent: my price, the lowest price, and the competitor that has it.

</Accordion>
<Accordion title="Find gaps in my assortment">

**Use case**

Find the products that your competitors sell and you do not. A paid matching also matches the competitors with each other, so the matches export has these products.

**Prompt**

> Get the matches export of my DeepScout project `[Default project]` and the product export of each website in it. My website is `[my-shop.cz]`. List the products that two or more competitors sell and my website does not. Give the name, the competitors and the lowest price. Sort them by the number of competitors.

</Accordion>
<Accordion title="Status of my jobs and credit">

**Use case**

See what runs now and how much credit is left, for example at the start of the day.

**Prompt**

> Show me the state of all websites in my DeepScout projects. For each running job, give the progress and the time left. Then show the spendable credit of my customer.

</Accordion>
</Accordions>

## FAQ [#faq]

<Accordions type="single">
<Accordion title="What can the agent see and do?">

The OAuth sign-in gives the app a key with the scope **All my projects**. The app can do everything that your [roles](/api/authentication.md#roles) let you do in all your projects. This includes the approval of jobs, which uses the credit of the customer.

To keep an agent inside one project, give it a key for this project. See [Use an API key](#use-an-api-key).

</Accordion>
<Accordion id="use-an-api-key" title="Can I use an API key instead of the sign-in?">

Yes. Create a key in the console, under **Settings → API keys**, and send it in the `Authorization` header. The server then skips the sign-in.

```bash title="Claude Code"
claude mcp add --transport http deepscout https://mcp.deepscout.ai/mcp \
  --header "Authorization: Bearer $SCOUT_API_KEY"
```

```json title="mcp.json"
{
  "mcpServers": {
    "deepscout": {
      "url": "https://mcp.deepscout.ai/mcp",
      "headers": { "Authorization": "Bearer your-api-key" }
    }
  }
}
```

A key for one project works only in this project. With this key, `scout_get_balance` fails with `403 INSUFFICIENT_SCOPE`, and all other tools work. See [Key scopes](/api/authentication.md#key-scopes).

</Accordion>
<Accordion title="How do I disconnect an app?">

Open the console, go to **Settings → API keys** and find the app under **Connected apps**. Click the disconnect icon next to the app and confirm. The API revokes the key of the app. Within 5 minutes, the requests of the app get `401`.

When you sign in again from the same app, the app gets a new key. The new key replaces the earlier key of this app.

</Accordion>
<Accordion title="The sign-in shows &quot;Client ID '…' not found&quot;">

The client keeps a registration that DeepScout deleted. DeepScout deletes the registration of an app 30 days after you disconnect it. If the first sign-in of an app does not finish, DeepScout deletes its registration after 30 days. Remove the saved sign-in data from the client, then sign in again:

- **Claude Code**: run `/mcp`, select **deepscout**, then **Clear authentication**. Then select **Authenticate**.
- **mcp-remote**: remove the folder `~/.mcp-auth`, then restart the client.
- **Other clients**: remove the server and add it again.

</Accordion>
<Accordion title="A tool returns an error">

A tool error contains the HTTP status, the error code and the details of the API error. For example, `HTTP 402 INSUFFICIENT_FUNDS` comes with `missing_topup`, the amount to add. Look up the code in [Errors](/api/errors.md).

The agent cannot top up the credit. To top up, use the console or the [top-up endpoint](/api/credits.md#top-up-the-credit).

</Accordion>
<Accordion title="A job runs for hours. Is it stuck?">

A job without an error is not stuck. DeepScout reads the pages of an e-shop at a rate that the e-shop accepts, so a large catalog takes many hours. See [Jobs](/api/jobs.md).

You do not need to keep the conversation open. Ask again later, in a new conversation. `scout_list_websites` shows the current job of each website.

</Accordion>
<Accordion title="The connection stops or the server does not answer">

Disconnect the server in the MCP settings of your client and connect it again. Your sign-in and your data stay the same.

</Accordion>
</Accordions>