> 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/products/pt-br/headless-browser/ai-workflows/integration-with-mcp.md).
# Integração com MCP
O Headless Browser pode ser usado com MCP, permitindo que sistemas de IA controlem navegadores remotos. Saiba mais sobre essa integração.
Este guia explica como integrar [**Oxylabs Headless Browser**](https://oxylabs.io/products/headless-browser) com o MCP (Model Context Protocol) para permitir que sistemas de IA interajam com navegadores remotos e os controlem.
{% hint style="success" %}
Visite o repositório GitHub da Oxylabs para um exemplo funcional completo de [**integração MCP com o Oxylabs Headless Browser**](https://github.com/oxylabs/oxylabs-hb-mcp)**.**
{% endhint %}
## Visão geral
O Model Control Protocol (MCP) permite que sistemas de IA como Claude interajam com navegadores e executem tarefas baseadas na web. Ao integrar o Oxylabs Headless Browser com MCP, você pode implementar sistemas de IA para realizar **navegação na web, recuperação de dados e automação** tarefas usando navegadores remotos com recursos avançados de navegação autônoma e [**proxy residencial**](https://oxylabs.io/products/residential-proxy-pool) integração.
O host MCP (como [**Claude Desktop**](https://claude.ai/download) ou [**Cursor**](https://www.cursor.com/)) vem com um cliente MCP integrado. Playwright-MCP atua como um servidor MCP e, em vez de usar um navegador local, ele se conecta ao Headless Browser por meio de uma conexão WebSocket segura (WSS).
## Primeiros passos
Antes de configurar a integração, verifique se você tem:
1. **conta Oxylabs**: obtenha seu `nome de usuário` e `senha` para o Headless Browser em [**painel da Oxylabs**](https://dashboard.oxylabs.io/en/registration).
2. **Node.js**: versão `18.0.0` ou superior (inclui `npm`/`npx`)
* **Windows**: baixe e instale a partir de [**nodejs.org**](https://nodejs.org/)
* **macOS**: use o Homebrew (`brew install node`) ou baixe em [**nodejs.org**](https://nodejs.org/)
* **Linux**:
* Ubuntu/Debian: `sudo apt update && sudo apt install nodejs npm`
* Fedora: `sudo dnf install nodejs npm`
* Ou baixe em [**nodejs.org**](https://nodejs.org/)
3. **Host MCP**: seja o Claude Desktop ou o Cursor instalados.
## Configure o servidor MCP
Crie uma seção de configuração do servidor MCP com suas credenciais da Oxylabs. Substitua `USERNAME` e `PASSWORD` pelas suas credenciais reais da Oxylabs:
```json
"oxylabs_headless_browser": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--cdp-endpoint",
"wss://USERNAME:PASSWORD@hb.oxylabs.io"
]
}
```
### Opção 1: integração com Cursor
1. Abra o Cursor
2. Abra as configurações do Cursor
3. Selecione MCP
4. Adicione a configuração do servidor MCP preparada
5. Reinicie o Cursor
### Opção 2: integração com Claude Desktop
1. Abra o Claude Desktop
2. Abra as configurações do Claude Desktop
3. Vá para Developer
4. Pressione Edit Config
5. Edite o `claude_desktop_config.json` arquivo
6. Adicione a configuração do servidor MCP preparada
7. Reinicie o Claude Desktop
## Opções avançadas de configuração
### Seleção de país
Você pode especificar um país para sua sessão de navegador adicionando o `?p_cc` parâmetro à sua URL de conexão:
```json
"oxylabs_headless_browser": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--cdp-endpoint",
"wss://USERNAME:PASSWORD@hb.oxylabs.io?p_cc=US"
]
}
```
Substitua `US` pelo código de país ISO-3166 desejado. Se nenhum país for especificado, o sistema atribuirá automaticamente um com base na disponibilidade.
{% hint style="success" %}
Você pode encontrar a lista de **códigos de país ISO-3166** [**aqui**](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).
{% endhint %}
Você também pode usar `p_state` ou `p_city` para segmentação por estado (US) ou cidade, ou use proxies residenciais sticky para um controle mais preciso do IP de saída. Saiba mais [**aqui**](/products/pt-br/headless-browser/geolocation-and-proxy-selection.md).
## Solução de problemas
Se você encontrar problemas com a integração:
1. **Problemas de conexão**:
* Verifique suas credenciais da Oxylabs
* Verifique sua conexão de rede
* Certifique-se de que os firewalls não estejam bloqueando conexões WebSocket
2. **Problemas de desempenho**:
* Para usuários baseados nos EUA, tente os endpoints específicos dos EUA
* Aumente os timeouts na sua configuração, se necessário
3. **Navegador não carrega**:
* Verifique a versão do Node.js (deve ser `18.0.0` ou superior)
* Verifique se `npx` está instalado corretamente
* Reinicie o aplicativo host MCP
---
# 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/products/pt-br/headless-browser/ai-workflows/integration-with-mcp.md?ask=&goal=
```
`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.
