> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/integrations/pt-br/ai-studio-integrations/protocolo-de-contexto-do-modelo-mcp.md).

# Protocolo de Contexto do Modelo (MCP)

Use o MCP da Oxylabs para fornecer a assistentes de IA ferramentas de scraping web, busca e extração em tempo real por meio do Web Scraper API e do AI Studio.

O servidor MCP da Oxylabs conecta assistentes de IA ([Claude](https://claude.ai/), [Cursor](https://www.cursor.com/), e qualquer outro [Model Context Protocol](https://modelcontextprotocol.io/) cliente) à web do mundo real.

Depois de conectado, seu assistente pode raspar qualquer URL (inclui renderização JavaScript e segmentação geográfica), pesquisar na web, rastrear sites e extrair dados estruturados.

{% hint style="success" %}
**Código-fonte aberto e registro:** Veja o código-fonte no [GitHub](https://github.com/oxylabs/oxylabs-mcp). O servidor está oficialmente registrado no [MCP Registry](https://registry.modelcontextprotocol.io/) (`io.oxylabs/oxylabs-mcp`), [PyPI](https://pypi.org/project/oxylabs-mcp/), e [Smithery](https://smithery.ai/).
{% endhint %}

## Pré-requisitos

Você precisa de **pelo menos um** conjunto de credenciais para desbloquear suas ferramentas correspondentes. Fornecer ambos desbloqueia todas as ferramentas listadas abaixo.

<table><thead><tr><th width="287">Credenciais</th><th width="307">Onde obter</th><th width="165">Desbloqueia</th></tr></thead><tbody><tr><td>Web Scraper API <code>nome de usuário</code> &#x26; <code>senha</code></td><td><a href="https://dashboard.oxylabs.io/">painel da Oxylabs</a> (teste grátis disponível)</td><td>ferramentas do Web Scraper API</td></tr><tr><td>chave de API do AI Studio</td><td><a href="https://aistudio.oxylabs.io/settings/api-key">Configurações do AI Studio</a> (créditos grátis incluídos)</td><td>ferramentas do AI Studio</td></tr></tbody></table>

{% hint style="warning" %}
Configure apenas as credenciais que você realmente tiver. Valores placeholder expõem ferramentas que falharão quando chamadas.
{% endhint %}

## Ferramentas disponíveis

<table><thead><tr><th width="204">Ferramenta</th><th width="428">O que faz</th><th width="133">Requer</th></tr></thead><tbody><tr><td><code>universal_scraper</code></td><td>Raspa qualquer URL. Renderização JavaScript opcional, segmentação geográfica, saída em Markdown/HTML</td><td>Web Scraper API</td></tr><tr><td><code>google_search_scraper</code></td><td>Resultados da Pesquisa Google, opcionalmente analisados em JSON estruturado</td><td>Web Scraper API</td></tr><tr><td><code>amazon_search_scraper</code></td><td>Páginas de resultados de pesquisa da Amazon, opcionalmente analisadas</td><td>Web Scraper API</td></tr><tr><td><code>amazon_product_scraper</code></td><td>Páginas individuais de produto da Amazon</td><td>Web Scraper API</td></tr><tr><td><code>ai_scraper</code></td><td>Extração com IA de qualquer URL (JSON, CSV, Markdown, TOON)</td><td>AI Studio</td></tr><tr><td><code>ai_crawler</code></td><td>Rastreamento de várias páginas e coleta de dados guiados por prompt </td><td>AI Studio</td></tr><tr><td><code>ai_browser_agent</code></td><td>Controle do navegador guiado por prompt: navegar, clicar, preencher formulários</td><td>AI Studio</td></tr><tr><td><code>ai_search</code></td><td>Pesquisa na web com conteúdo opcional em Markdown de cada resultado</td><td>AI Studio</td></tr><tr><td><code>ai_map</code></td><td>Mapeia URLs de sites</td><td>AI Studio</td></tr><tr><td><code>generate_schema</code></td><td>Gera esquemas de extração personalizados para as ferramentas do AI Studio</td><td>AI Studio</td></tr></tbody></table>

## Escolha como conectar

<table data-header-hidden><thead><tr><th width="117"></th><th>Hospedado (recomendado)</th><th>Local</th></tr></thead><tbody><tr><td></td><td><a href="#option-1-hosted-server-recommended"><strong>Servidor hospedado</strong></a> (recomendado)</td><td><a href="#option-2-run-the-server-locally"><strong>Servidor local</strong></a></td></tr><tr><td><strong>Instalar</strong></td><td>Nenhum</td><td><a href="https://docs.astral.sh/uv/">uv</a> + <code>uvx oxylabs-mcp</code></td></tr><tr><td><strong>Ponto de extremidade</strong></td><td><code>https://mcp.oxylabs.io/mcp</code></td><td>Cursor/Claude iniciam o processo</td></tr><tr><td><strong>Credenciais</strong></td><td>Cabeçalhos HTTP</td><td>Variáveis de ambiente</td></tr><tr><td><strong>Melhor para</strong></td><td>Configuração mais rápida, sem gerenciamento</td><td>Controle offline, depuração local, clientes que não podem enviar cabeçalhos personalizados</td></tr></tbody></table>

## Método 1: Servidor hospedado (recomendado)

Conecte-se ao servidor MCP hospedado da Oxylabs:

```
https://mcp.oxylabs.io/mcp
```

Passe as credenciais como cabeçalhos da requisição:

<table><thead><tr><th width="240">Credencial</th><th>Cabeçalho</th></tr></thead><tbody><tr><td>Web Scraper API</td><td><code>Authorization: Basic &#x3C;base64(username:password)></code></td></tr><tr><td>AI Studio</td><td><code>X-Oxylabs-AI-Studio-Api-Key: &#x3C;your API key></code></td></tr></tbody></table>

{% hint style="warning" %}
**Nota:** Inclua apenas os cabeçalhos das credenciais que você tiver.
{% endhint %}

### Claude Code

Instale diretamente na linha de comando:

```bash
claude mcp add --transport http oxylabs https://mcp.oxylabs.io/mcp \
  --header "Authorization: Basic $(echo -n 'YOUR_USERNAME:YOUR_PASSWORD' | base64)" \
  --header "X-Oxylabs-AI-Studio-Api-Key: YOUR_API_KEY"
```

Omita uma `--header` linha se você não tiver essa credencial.

### Claude Desktop

O editor de configuração integrado do Claude Desktop usa servidores locais (`command`) . Para o endpoint hospedado, use Claude Code com o comando HTTP acima, ou [execute o servidor localmente](#claude-desktop-2) e aponte o Claude Desktop para essa configuração.

### Cursor

1. Abra **Configurações do Cursor** → **Personalizar** na barra lateral → **MCPs**
2. Clique em **+ Novo**
3. Escolha **Usuário** (todos os projetos) ou **Projeto** (somente no workspace)
4. Adicione o seguinte ao `mcp.json`:<br>

   ```json
   {
     "mcpServers": {
       "oxylabs": {
         "url": "https://mcp.oxylabs.io/mcp",
         "headers": {
           "Authorization": "Basic <base64 of username:password>",
           "X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY"
         }
       }
     }
   }
   ```
5. Salve e, em seguida, confirme que o servidor está ativado em **Personalizar → MCPs**.

{% hint style="info" %}
**Nota:** *Usuário* escreve em `~/.cursor/mcp.json`. *Workspace* escreve em `.cursor/mcp.json` no workspace escolhido. Se ambos definirem o mesmo nome de servidor, a *configuração do workspace* tem prioridade.
{% endhint %}

## Método 2: Servidor local

O servidor está disponível em nosso [repositório PyPI](https://pypi.org/project/oxylabs-mcp/).&#x20;

Se ainda não estiver instalado, instale o [pacote uv](https://docs.astral.sh/uv/) de acordo com o sistema operacional escolhido:

{% tabs %}
{% tab title="macOS / Linux" %}

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

{% endtab %}

{% tab title="Windows" %}

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

{% endtab %}
{% endtabs %}

As credenciais são passadas como variáveis de ambiente (defina **somente** as que você tiver):

| Variável                    | Descrição                          |
| --------------------------- | ---------------------------------- |
| `OXYLABS_USERNAME`          | nome de usuário do Web Scraper API |
| `OXYLABS_PASSWORD`          | senha do Web Scraper API           |
| `OXYLABS_AI_STUDIO_API_KEY` | chave de API do AI Studio          |

### Claude Code

```bash
claude mcp add oxylabs -- command uvx args oxylabs-mcp \
  --env OXYLABS_USERNAME=YOUR_USERNAME \
  --env OXYLABS_PASSWORD=YOUR_PASSWORD \
  --env OXYLABS_AI_STUDIO_API_KEY=YOUR_API_KEY
```

{% hint style="info" %}
Caminho de configuração manual para Claude Code: `~/.config/claude/mcp.json` (macOS/Linux) ou `%USERPROFILE%\.config\claude\mcp.json` (Windows). A estrutura JSON corresponde ao Claude Desktop.
{% endhint %}

### Claude Desktop

1. Abra **Claude → Configurações → Desenvolvedor → Editar Config**
2. Adicione o seguinte a `claude_desktop_config.json`:<br>

   ```json
   {
     "mcpServers": {
       "oxylabs": {
         "command": "uvx",
         "args": ["oxylabs-mcp"],
         "env": {
           "OXYLABS_USERNAME": "YOUR_USERNAME",
           "OXYLABS_PASSWORD": "YOUR_PASSWORD",
           "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
         }
       }
     }
   }
   ```
3. Reinicie o Claude Desktop

### Cursor

1. Abra **Configurações do Cursor** → **Personalizar** na barra lateral → **MCPs**
2. Clique em **+ Novo**
3. Escolha **Usuário** (todos os projetos) ou **Projeto** (somente no workspace)
4. Adicione o seguinte ao `mcp.json`:<br>

   ```json
   {
     "mcpServers": {
       "oxylabs": {
         "command": "uvx",
         "args": ["oxylabs-mcp"],
         "env": {
           "OXYLABS_USERNAME": "YOUR_USERNAME",
           "OXYLABS_PASSWORD": "YOUR_PASSWORD",
           "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
         }
       }
     }
   }
   ```
5. Salve e, em seguida, confirme que o servidor está ativado em **Personalizar → MCPs**.

{% hint style="info" %}
**Nota:** *Usuário* escreve em `~/.cursor/mcp.json`. *Workspaces* escreve em `.cursor/mcp.json` no workspace escolhido. Se ambos definirem o mesmo nome de servidor, a *configuração do workspace* tem prioridade.
{% endhint %}

## Verifique a configuração

Depois de conectar, peça ao seu assistente algo que exija dados da web em tempo real (por exemplo, `“Raspe https://ip.oxylabs.io e retorne o conteúdo como Markdown.”`):

{% stepper %}
{% step %}
Confirme que o `oxylabs` servidor aparece e está ativado na lista MCP do seu cliente.
{% endstep %}

{% step %}
Aprove a chamada da ferramenta quando solicitado (os clientes pedem confirmação antes de executar ferramentas MCP por padrão).
{% endstep %}

{% step %}
Se a chamada falhar, verifique as credenciais e os logs do cliente (Cursor: **Saída → MCP Logs**).
{% endstep %}
{% endstepper %}

## Solução de problemas

<table><thead><tr><th width="251">Erro</th><th>Solução</th></tr></thead><tbody><tr><td>Servidor ausente no cliente</td><td>Reinicie o app após editar a configuração. Confirme que o JSON é válido.</td></tr><tr><td>Ferramentas listadas, mas as chamadas falham</td><td>Credenciais placeholder, Base64 incorreto ou cabeçalho/variável de ambiente ausente para essa ferramenta.</td></tr><tr><td>A URL hospedada não conecta</td><td>O cliente pode não suportar cabeçalhos personalizados; use a configuração local.</td></tr><tr><td><code>uvx</code> comando não encontrado</td><td>Instalar <a href="https://docs.astral.sh/uv/">uv</a> e certifique-se de que ele esteja no seu <code>PATH</code>.</td></tr><tr><td>O caminho na interface do Cursor parece diferente</td><td>Ignore a interface e edite <code>mcp.json</code> diretamente (os rótulos podem mudar entre versões do Cursor).</td></tr></tbody></table>

{% hint style="success" %}
Para problemas ou solicitações de recurso, abra um issue no GitHub ou contate o suporte 24/7 da Oxylabs em [**support@oxylabs.io**](mailto:support@oxylabs.io).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/integrations/pt-br/ai-studio-integrations/protocolo-de-contexto-do-modelo-mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.