> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup e Integração

> Configure Topsort Prompts e integre via Agent API ou MCP.

## Opções de integração

* **Agent API**: melhor para chat e conversas multi-turno
* **MCP Server**: melhor para integrações customizadas e acesso direto às ferramentas

## Opção 1: Agent API

### Endpoint

```text theme={null}
POST /topsort_prompts/chat
```

### Headers

```http theme={null}
X-API-Key: YOUR_API_KEY
Content-Type: application/json
```

### Exemplo de request

```json theme={null}
{
  "query": "I need running shoes under $150",
  "session_id": "user-session-123",
  "max_results": 10,
  "max_sponsored": 3,
  "streaming": false
}
```

Campos principais: `query`, `session_id`, `max_results`, `max_sponsored`, `streaming`.

## Opção 2: MCP Server

### Conexão

```text theme={null}
URL: https://mcp-server.api.topsort.ai/mcp
Transport: Streamable HTTP
```

```http theme={null}
X-API-Key: YOUR_API_KEY
```

Use a ferramenta `search_products` com parâmetros como `query`, `max_results` e `max_sponsored`.

## Boas práticas

* Identifique claramente produtos patrocinados (`is_sponsored: true`)
* Rastreie `resolvedBidId` para atribuição
* Reuse `session_id` para manter contexto
* Implemente retry com backoff para erros `5xx`