GeckoAPI
Entrar Agendar uma demo

// docs

Docs do MCP hospedado

Como integrar agentes MCP com o endpoint remoto /v1/mcp da GeckoAPI, usando tools por seam e o mesmo contrato de inputs do /v1/extract.

Endpoint

https://api.geckoapi.com.br/v1/mcp

Métodos

POST somente

Autenticação

Bearer ou X-API-Key

Escopo

34 tools backend-supported

A v1 usa autenticação por chave estática de API. OAuth não faz parte desta versão. O servidor é stateless, responde em JSON no POST e retorna 405 para GET e DELETE.

Configuração do servidor MCP

Se o seu cliente permitir configurar headers diretamente, use o endpoint remoto com Authorization: Bearer pk_live_.... O backend também aceita X-API-Key por compatibilidade.

mcpServers.geckoapi 
{
  "mcpServers": {
    "geckoapi": {
      "url": "https://api.geckoapi.com.br/v1/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_sua_chave"
      }
    }
  }
}

Fluxo JSON-RPC

initialize 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "seu-cliente-mcp",
      "version": "1.0.0"
    }
  }
}
tools/list 
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

O tools/list retorna somente tools habilitados para a conta autenticada. O custo atual em créditos aparece na descrição de cada tool.

Naming das tools

O nome da tool é derivado do apiId do backend. Na prática, o hostname vira snake_case ASCII e o tipo é preservado no final.

apiId tool Doc seam
mercadolivre.com.br:pdp mercadolivre_com_br_pdp Mercado Livre PDP
ifood.com.br:plp ifood_com_br_plp iFood PLP

Exemplos de tools/call

Os argumentos seguem exatamente os mesmos nomes do POST /v1/extract, com uma diferença importante: target e type já ficam fixos pela tool e não aparecem no schema do MCP. O campo executionId é opcional e serve para idempotência/dedupe.

mercadolivre_com_br_pdp 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "mercadolivre_com_br_pdp",
    "arguments": {
      "url": "https://produto.mercadolivre.com.br/MLB-4196330777-acrilico-toque-de-seda-premium-leve-brilho-16l-suvinil-_JM",
      "executionId": "exec_example_123"
    }
  }
}
ifood_com_br_plp 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "ifood_com_br_plp",
    "arguments": {
      "keyword": "marmita",
      "zipCode": "80010-000",
      "page": 1,
      "executionId": "exec_example_123"
    }
  }
}

Formato das respostas

Em sucesso, o conteúdo estruturado segue o envelope do extract: requestId, executionId e data. Em falha de tool, o servidor retorna isError: true com payload estruturado.

Call result OK 
{
  "content": [
    {
      "type": "text",
      "text": "{\"requestId\":\"req_123\",\"executionId\":\"exec_example_123\",\"data\":{\"title\":\"Produto exemplo\",\"price\":199.9}}"
    }
  ],
  "structuredContent": {
    "requestId": "req_123",
    "executionId": "exec_example_123",
    "data": {
      "title": "Produto exemplo",
      "price": 199.9
    }
  }
}
Call result error 
{
  "content": [
    {
      "type": "text",
      "text": "{\"statusCode\":402,\"errorCode\":\"INSUFFICIENT_CREDITS\",\"message\":\"Not enough credits\",\"requestId\":\"req_402\",\"details\":{\"requiredCredits\":5,\"availableCredits\":0}}"
    }
  ],
  "structuredContent": {
    "statusCode": 402,
    "errorCode": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits",
    "requestId": "req_402",
    "details": {
      "requiredCredits": 5,
      "availableCredits": 0
    }
  },
  "isError": true
}

Como navegar pelos seams

Cada página de seam em /docs/<slug> agora mostra o exemplo HTTP e o exemplo MCP para a mesma API, usando o mesmo conjunto de campos suportados.

Grátis para sempre

Validar uma tool específica?

Abra a página de cada seam para copiar o payload HTTP ou o tools/call correspondente ao seu caso de uso.

Explorar docs de seams Ver exemplos de uso
WhatsApp