Servidor MCP da Messora

A Messora expõe um Model Context Protocol (MCP) server remoto em Streamable HTTP. Ele permite que agentes LLM (Claude, Codex, Cursor e outros clientes MCP) chamem scrape, crawl, search e consultem jobs e uso — reutilizando a mesma conta, a mesma API key e a mesma pool de créditos da REST API.

Endpoint

Recurso	URL
MCP	`https://mcp.messora.dev/mcp`
Health	`https://mcp.messora.dev/health`

O endpoint /health é independente do backend e retorna {"status": "ok", "service": "messora-mcp"} sem exigir autenticação.

Autenticação

O MCP usa exclusivamente o header Authorization: Bearer:

Authorization: Bearer $MESSORA_API_KEY

O header X-API-Key usado na REST API não é aceito pelo MCP. Use sempre Authorization: Bearer.

Você precisa de uma API key da Messora. Se ainda não tem, crie uma em www.messora.dev/auth/signup → API Keys.

Configurando clientes

Claude Desktop

O Claude Desktop usa um config JSON em ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "messora": {
      "type": "http",
      "url": "https://mcp.messora.dev/mcp",
      "headers": {
        "Authorization": "Bearer sua-api-key-aqui"
      }
    }
  }
}

Reinicie o Claude Desktop após salvar. As ferramentas da Messora aparecem no seletor de tools.

O Claude Desktop não suporta interpolação de variável de ambiente no config. Use um placeholder e substitua, ou coloque a key diretamente — o arquivo é local e não é versionado.

Cursor

O Cursor usa um arquivo .mcp.json na raiz do projeto ou ~/.cursor/mcp.json:

{
  "mcpServers": {
    "messora": {
      "type": "http",
      "url": "https://mcp.messora.dev/mcp",
      "headers": {
        "Authorization": "Bearer sua-api-key-aqui"
      }
    }
  }
}

Reinicie o Cursor ou rode Cursor → Settings → MCP → Refresh para carregar o servidor.

Codex CLI

O Codex usa um arquivo config.toml em ~/.codex/config.toml:

[mcp_servers.messora]
url = "https://mcp.messora.dev/mcp"
bearer_token_env_var = "MESSORA_API_KEY"

Exporte a API key no shell antes de iniciar o Codex:

export MESSORA_API_KEY="sua-api-key-aqui"

MCP Inspector

export MESSORA_API_KEY="sua-api-key-aqui"
npx @modelcontextprotocol/inspector

No Inspector, configure:

Transport type: Streamable HTTP
URL: https://mcp.messora.dev/mcp
Authentication: Bearer token
Token env var: MESSORA_API_KEY

Nunca coloque a API key literalmente em arquivos de configuração versionados. Para o Codex, use sempre variável de ambiente ($MESSORA_API_KEY). Para Claude Desktop e Cursor, o config é local (não versionado) — substitua o placeholder pela sua key.

Ferramentas disponíveis

O servidor expõe exatamente cinco tools:

`scrape_url`

Extrai conteúdo de uma URL. Consome crédito somente quando o backend retorna scrape_status = success.

Parâmetro	Tipo	Default	Descrição
`url`	string (URI)	obrigatório	URL alvo
`formats`	`["markdown"]`	`["markdown"]`	Formatos: `markdown`, `json`, `raw`
`json_schema`	object	—	Obrigatório se `formats` inclui `json`
`render_js`	boolean	`false`	Renderizar JavaScript
`only_main_content`	boolean	`false`	Somente conteúdo principal
`timeout`	int (1–180)	`60`	Timeout em segundos
`max_pages`	int (1–50)	`1`	Máximo de páginas
`parse_pdf`	boolean	`true`	Processar PDFs
`tags`	string[]	—	Até 10 tags (64 chars cada)

`start_crawl`

Inicia um crawl assíncrono e retorna job_id. Consulte get_job até o estado virar SUCCESS, FAILURE ou REVOKED.

Parâmetro	Tipo	Default	Descrição
`url`	string (URI)	obrigatório	URL semente
`max_pages`	int (1–50)	obrigatório	Teto de páginas
`max_depth`	int ≥ 0	—	Profundidade máxima do BFS
`only_main_content`	boolean	`true`	Somente conteúdo principal
`timeout_ms`	int (1000–300000)	`60000`	Timeout por página
`tags`	string[]	`[]`	Tags de uso

`start_search`

Inicia uma busca premium assíncrona e retorna job_id.

Parâmetro	Tipo	Default	Descrição
`query`	string	obrigatório	Query de busca
`num_results`	int (10–100)	`10`	Número de resultados
`country`	string (ISO alpha-2)	—	Ex.: `BR`, `US`
`freshness`	`day\|week\|month\|year\|any`	—	Recência
`tags`	string[]	—	Até 10 tags
`query_fanout`	boolean	`true`	Expande a query em até 5 variantes via LLM. `false` busca só a query crua — mais rápido, com 1 chamada LLM a menos (o score de relevância continua rodando)
`use_cache`	boolean	`false`	Reutiliza um resultado completo dos últimos 10 minutos para a mesma query e filtros

`get_job`

Consulta o estado de um job de crawl ou search.

Parâmetro	Tipo	Descrição
`job_id`	string	UUID retornado por `start_crawl` ou `start_search`

Estados: PENDING → STARTED → SUCCESS | FAILURE | REVOKED

Recomendamos polling a cada 2 segundos com backoff. O adaptador MCP não faz polling interno nem retry automático de operações cobradas.

`get_usage`

Consulta plano, créditos usados e saldo da conta. Sem argumentos de produto. Mesmo payload do REST GET /account/usage.

Passo-a-passo completo: os cinco tools em um fluxo

Os cinco tools têm padrões diferentes: síncrono (scrape_url), assíncrono com polling (start_crawl, start_search → get_job), e query (get_usage). Aqui está uma sequência realista:

// 1. Scrape síncrono: URL única, resposta imediata
const singlePage = await mcp.call_tool('scrape_url', {
  url: 'https://example.com/artigo',
  formats: ['markdown', 'json'],
  json_schema: { type: 'object', properties: { title: { type: 'string' } } }
})
// → {"ok": true, "data": {"markdown": "# Artigo...", "json": {"title": "..."}, ...}, "success": true}

// 2. Crawl assíncrono: múltiplas URLs, retorna job_id, faz polling até terminar
const crawlJob = await mcp.call_tool('start_crawl', {
  url: 'https://example.com',
  max_pages: 10
})
// → {"ok": true, "data": {"job_id": "abc-123", "status": "PENDING"}, ...}

// 3. Faz polling do status do job
let jobStatus = await mcp.call_tool('get_job', {
  job_id: crawlJob.data.job_id
})
// → {"ok": true, "data": {"status": "STARTED", "meta": {"pages_done": 3, "max_pages": 10}}, ...}

// Repete #3 a cada 2 segundos até status = "SUCCESS" ou "FAILURE"
while (jobStatus.data.status === 'STARTED') {
  await new Promise(r => setTimeout(r, 2000))
  jobStatus = await mcp.call_tool('get_job', { job_id: crawlJob.data.job_id })
}
// → {"ok": true, "data": {"status": "SUCCESS", "results": [...], "credits_used": 10}, ...}

// 4. Search assíncrono: similar ao crawl — job_id + polling
const searchJob = await mcp.call_tool('start_search', {
  query: 'machine learning',
  num_results: 20
})
// → {"ok": true, "data": {"job_id": "xyz-789", "status": "PENDING"}, ...}

// Faz polling até sucesso (mesmo padrão do crawl)
let searchStatus = await mcp.call_tool('get_job', { job_id: searchJob.data.job_id })
// → eventualmente {"status": "SUCCESS", "results": [{...}, ...]}

// 5. Query de uso: sem params, resposta imediata
const usage = await mcp.call_tool('get_usage', {})
// → {"ok": true, "data": {"plan": "pro", "credits_used": 1050, "remaining_credits": 1450}, ...}

Quando usar cada uma:

scrape_url — uma URL, precisa resultado agora (markdown/JSON estruturado/HTML bruto)
start_crawl + get_job — múltiplas URLs no mesmo domínio, em background, lote final de resultados
start_search + get_job — busca por query em conteúdo indexado, em background
get_usage — verifica plano e saldo de créditos antes/depois de operações em lote

Fluxo assíncrono: `start_*` → `get_job`

Crawl e search são assíncronos no backend. O fluxo recomendado é:

start_crawl(url, max_pages=3)
  → {"job_id": "d8cc042a-dcbb-4f8b-a159-91fd47d060f9", "status": "PENDING", "next_action": "Call get_job..."}

get_job(job_id="d8cc042a-dcbb-4f8b-a159-91fd47d060f9")
  → {"status": "STARTED", "meta": {"pages_done": 1, "max_pages": 3}}

get_job(job_id="d8cc042a-dcbb-4f8b-a159-91fd47d060f9")
  → {"status": "SUCCESS", "credits_used": 3, "results": [...]}

Tamanho de resposta

Toda resposta de tool é limitada a 100.000 caracteres. Se excedir, campos textuais (markdown, rawHtml) são truncados preservando estrutura, status, metering e JSON válido:

{
  "ok": true,
  "data": { "status": "SUCCESS", "credits_used": 3, "results": [...] },
  "output": { "truncated": true, "original_chars": 250000, "returned_chars": 99500 }
}

Erros

HTTP	Código MCP	Retry	Significado
401	`missing_api_key`	não	Credencial ausente
402	`insufficient_credits`	não	Créditos insuficientes
403	`invalid_or_revoked_api_key`	não	Key inválida ou revogada
404	`not_found`	não	Job inexistente ou de outra conta
422	`validation_error`	não	Input inválido
429	`rate_limit_exceeded`	sim	Limite excedido (preserva `Retry-After`)
5xx	`backend_unavailable`	sim	Falha temporária no backend
—	`backend_timeout`	sim	Timeout de rede

Em resposta não-2xx o adaptador descarta o corpo do backend por completo e deriva o error.message só do status HTTP (sempre em inglês). Ramifique por error.code, nunca por error.message:

HTTP	`error.message`
401	`Authentication required`
402	`Insufficient credits`
403	`Invalid or revoked API key`
404	`Resource not found`
422	`Invalid request parameters`
429	`Rate limit exceeded`
demais 4xx	`Request rejected by the backend`
5xx	`Temporary backend failure`

Input que o próprio adaptador valida (formats duplicado, json_schema ausente no formato json, pdf_ocr sem parse_pdf, sobreposição de include_domains/exclude_domains, job_id malformado) retorna validation_error com mensagem específica nomeando o campo. O corpo de resposta 2xx é repassado, então o texto de sistema dentro dele é normalizado para inglês: job em FAILURE retorna o valor fixo data.error = "The job could not be completed. Try again.", e job de search em STARTED reporta meta.stage como starting ou running. Conteúdo extraído da web (results) nunca é reescrito. data.json sempre traz exatamente os campos que o json_schema declara — o backend nunca injeta chave extra nele, nem uma chamada error. Se a extração falhar por completo, todo campo declarado vem null e um campo irmão, data.json_extraction_error_code (hoje só "extraction_failed"), reporta a falha em vez disso. Quando esse código está presente, o MCP adiciona data.json_extraction_error_message com o texto fixo em inglês "Structured extraction failed for this schema. Try again or adjust json_prompt/json_schema.". Se o seu schema declara sua própria property error, ela nunca é tocada — esse campo só carrega o que o seu schema pediu, em sucesso ou falha. _extraction_failed é reservado para esse sinal interno e rejeitado como nome de property do json_schema (validation_error).

O MCP é um adaptador fino: auth, billing, rate limit e jobs pertencem ao backend FastAPI. Os mesmos limites e custos da REST API se aplicam.

Início

Integrações

Playground

Servidor MCP

Servidor MCP da Messora

Endpoint

Autenticação

Configurando clientes

Claude Desktop

Cursor

Codex CLI

MCP Inspector

Ferramentas disponíveis

`scrape_url`

`start_crawl`

`start_search`

`get_job`

`get_usage`

Passo-a-passo completo: os cinco tools em um fluxo

Fluxo assíncrono: `start_*` → `get_job`

Tamanho de resposta

Erros

​Servidor MCP da Messora

​Endpoint

​Autenticação

​Configurando clientes

​Claude Desktop

​Cursor

​Codex CLI

​MCP Inspector

​Ferramentas disponíveis

​scrape_url

​start_crawl

​start_search

​get_job

​get_usage

​Passo-a-passo completo: os cinco tools em um fluxo

​Fluxo assíncrono: start_* → get_job

​Tamanho de resposta

​Erros

Servidor MCP da Messora

Endpoint

Autenticação

Configurando clientes

Claude Desktop

Cursor

Codex CLI

MCP Inspector

Ferramentas disponíveis

`scrape_url`

`start_crawl`

`start_search`

`get_job`

`get_usage`

Passo-a-passo completo: os cinco tools em um fluxo

Fluxo assíncrono: `start_*` → `get_job`

Tamanho de resposta

Erros