# SeguroBet Analytics MCP

O SeguroBet Analytics MCP é um servidor MCP remoto que expõe dados analíticos da SeguroBet (ClickHouse, camada dw_gold_sb, read-only) para assistentes de IA. Acesso protegido por OAuth 2.1 com PKCE usando as contas do BI.

Endpoint MCP: https://mcp.segurobet.com.br/mcp (streamable-http, protocolo 2025-06-18)
Documentação: https://mcp.segurobet.com.br/docs (HTML dark theme)
Descoberta OAuth: https://mcp.segurobet.com.br/.well-known/oauth-authorization-server


## Links

- [Documentação (HTML)](https://mcp.segurobet.com.br/docs): Página de documentação — arquitetura, autenticação, referência das tools, snippets de conexão.
- [Documentação (Markdown)](https://mcp.segurobet.com.br/docs/index.md): Mesmo conteúdo em Markdown para leitura direta por LLMs e agentes.
- [Endpoint MCP](https://mcp.segurobet.com.br/mcp): Protocolo MCP sobre HTTP (exige Authorization: Bearer <access_token>).
- [Metadata OAuth](https://mcp.segurobet.com.br/.well-known/oauth-authorization-server): Descoberta OAuth 2.1 (authorization_endpoint, token_endpoint, scopes_supported).
- [BI API Swagger](https://bi.segurobet.com.br/v1/bi/docs): Relatórios pré-definidos do BI em formato OpenAPI.


## Autenticação

OAuth 2.1 Authorization Code + PKCE S256, delegado ao BI (https://bi.segurobet.com.br).

1. GET /oauth/authorize?client_id=segurobet-mcp&redirect_uri=<uri>&code_challenge=<s256>&... → login do BI
2. POST https://bi.segurobet.com.br/oauth/token com code + code_verifier → access_token + refresh_token
3. Todas as chamadas ao /mcp: Authorization: Bearer <access_token>


## Fluxo obrigatório para agentes

1. Chame `manual_de_uso` — carrega regras de negócio e fluxo da sessão.
2. Chame `buscar_conhecimento(pergunta)` — RAG (DDL, regras, exemplos) + emite `rules_token` (válido 15 min).
3. Chame `executar_sql(sql, rules_token, pergunta)` — executa SELECT read-only na gold após validar token e lint (máx. 200 linhas).

Regra dura: executar_sql recusa SQL sem rules_token válido. Só existe a camada dw_gold_sb. A data de hoje vem de dw_gold_sb.data_hoje (nunca now()/today()).