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.

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": "Chame 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

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`

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

​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`

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

Tamanho de resposta

Erros