NewsIntel MCP Server

MCP server para integrações dinâmicas com NewsIntel usando token do próprio usuário em cada chamada.

Objetivo: permitir que qualquer cliente de IA (secretaria, assistentes, apps de terceiros) use o mesmo contrato MCP, sem hardcode por usuário.

Sumário

• Arquitetura
• Pré-requisitos
• Instalação
• Executar
• Configuração
• Ferramentas MCP
• Exemplos de uso
• Modelo de erros
• Segurança
• Desenvolvimento
• FAQ

Arquitetura

O servidor roda via stdio e atua como proxy fino para a API NewsIntel:

1. Cliente MCP chama uma tool
2. Tool recebe apiToken do usuário final
3. Servidor chama endpoint NewsIntel correspondente
4. Retorna JSON estruturado para o cliente MCP

Sem estado local por usuário, sem sessão persistente no MCP.

Pré-requisitos

• Node.js >= 22
• Acesso HTTP ao endpoint da NewsIntel API
• Token de usuário NewsIntel (ni_live_...)

Instalação

cd integrations/newsintel-mcp
npm install

Executar

npm start

Isso inicia o servidor MCP em stdio (modo esperado por clientes MCP).

Configuração

Variáveis de ambiente suportadas:

| Variável | Obrigatória | Default | Descrição | |---|---:|---|---| | NEWSINTEL_API_BASE | não | https://newsintelapi.com | Base URL da API NewsIntel |

Exemplo:

NEWSINTEL_API_BASE=https://newsintelapi.com npm start

Ferramentas MCP

1) newsintel_sync_profile

Sincroniza/personaliza o perfil do usuário.

Input

• apiToken (string, obrigatório)
• mode (manual | x-browser | x-api, opcional, default manual)
• topics (string[], opcional)
• free_text (string, opcional)
• x_username (string, opcional)

Backend

• POST /v1/profile/sync

2) newsintel_get_profile

Busca perfil/interesses atuais do usuário.

Input

• apiToken (string, obrigatório)

Backend

• GET /v1/profile

3) newsintel_get_news_briefing

Busca notícias personalizadas com filtros.

Input

• apiToken (string, obrigatório)
• topics (string[], opcional)
• country (string, opcional, ex: BR, US)
• lang (string[], opcional, ex: ['pt','en'])
• limit (number, opcional, 5..50, default 20)

Backend

• GET /v1/news/search

Exemplos de uso

Sync manual com tópicos explícitos

{
  "apiToken": "ni_live_xxx",
  "mode": "manual",
  "topics": ["spfc", "crypto", "macro"]
}

Buscar perfil

{
  "apiToken": "ni_live_xxx"
}

Buscar briefing BR/PT

{
  "apiToken": "ni_live_xxx",
  "topics": ["spfc", "mercados"],
  "country": "BR",
  "lang": ["pt"],
  "limit": 20
}

Modelo de erros

Erros de API são retornados como:

newsintel_api_error <status>: <payload-json-truncado>

Exemplos comuns:

• 401/403: token inválido ou sem permissão
• 429: rate limit
• 5xx: indisponibilidade temporária

Recomendado no cliente:

• retry com backoff para 429/5xx
• refresh/reauth para 401/403

Segurança

• Trate apiToken como segredo.
• Não salve token em logs, analytics ou mensagens de erro públicas.
• Prefira injeção via secrets manager.
• Se houver suspeita de vazamento: rotacione o token imediatamente.

Desenvolvimento

Estrutura:

integrations/newsintel-mcp/
├── server.mjs
├── package.json
└── README.md

Checagem rápida de sintaxe:

node --check server.mjs

FAQ

Preciso de um MCP por usuário?

• Não. O mesmo servidor atende múltiplos usuários via apiToken por chamada.

Posso apontar para outra API base (staging)?

• Sim, usando NEWSINTEL_API_BASE.

Esse MCP guarda estado?

• Não. É stateless; toda personalização vem da API NewsIntel.