> ## Documentation Index > Fetch the complete documentation index at: https://docs.dadosfutebol.com.br/llms.txt > Use this file to discover all available pages before exploring further. # MCP (IA) > Conecte os dados de futebol a assistentes de IA (Claude, Cursor) via Model Context Protocol. # Servidor MCP O **MCP (Model Context Protocol)** é um padrão aberto que permite a assistentes de IA — como o Claude e o Cursor — chamarem ferramentas externas para buscar dados. A API Dados Futebol expõe um **servidor MCP** que transforma cada endpoint em uma *tool*: o assistente passa a consultar campeonatos, tabelas, partidas ao vivo, escalações, artilharia e muito mais diretamente na conversa. Por baixo dos panos, o servidor MCP usa uma **API Key** da sua conta e respeita **exatamente os mesmos planos e limites de requisições** da API REST. Não há cobrança nem cota separada — cada chamada de tool conta como uma requisição normal da sua key. ## Como funciona Por baixo, cada tool encaminha para o endpoint `/v1` correspondente. Isso significa que autenticação, restrição por plano, rate limit e o registro de uso são **idênticos** aos da API REST documentada em [Autenticação](/autenticacao). As respostas são o mesmo JSON em português, com o envelope `data`/`meta` em sucessos e `erro`/`mensagem` em falhas. Fluxo típico: o assistente descobre o `campeonato_id` com `listar-campeonatos`, depois pede a tabela, as rodadas ou as partidas daquele campeonato. ## Conexão A URL de conexão é só o endpoint — **sem chave, sem parâmetro nenhum**: ``` https://mcp.dadosfutebol.com.br ``` ```bash Claude Code theme={null} claude mcp add --transport http dadosfutebol "https://mcp.dadosfutebol.com.br" ``` Ou, editando o arquivo de config direto (`.claude.json` / `.mcp.json`): ```jsonc theme={null} { "mcpServers": { "dadosfutebol": { "type": "http", "url": "https://mcp.dadosfutebol.com.br" } } } ``` Ao conectar, o cliente MCP abre o navegador automaticamente. Faça login (ou crie conta) no portal e clique em **"Autorizar acesso via MCP"**. Os tokens emitidos expiram em **1 hora**, com renovação automática por até **30 dias**. Depois disso — ou se a renovação falhar — o cliente reabre o navegador para você reautorizar; não é preciso reconfigurar nada. Não quer montar a URL na mão? Acesse **`https://dadosfutebol.com.br/api-keys`**, entre com sua conta e copie a URL, o comando ou o JSON prontos no painel "Conectar via MCP". A forma antiga de conectar — embutindo a chave na URL com `?api_key=SUA_API_KEY` — foi **desativada** e agora retorna `401`. Se a sua configuração é de antes desta mudança, remova a chave da URL (deixe só `https://mcp.dadosfutebol.com.br`) e reconecte pelo fluxo OAuth acima. É preciso ter **ao menos uma chave de API ativa** na conta — gere uma em `https://dadosfutebol.com.br/api-keys` antes de conectar. O servidor MCP usa essa chave por baixo dos panos para aplicar o plano e os limites da sua conta; o fluxo OAuth só substitui a necessidade de colar/gerenciar a chave manualmente. ### Alternativa programática (sem navegador) Para scripts, CI ou integrações sem browser, o header `Authorization` com a API Key continua aceito — sem passar pelo fluxo OAuth: ```http theme={null} https://mcp.dadosfutebol.com.br Authorization: Bearer SUA_API_KEY ``` Configuração por cliente (substitua `SUA_API_KEY`): ```bash Claude Code theme={null} claude mcp add --transport http dadosfutebol \ https://mcp.dadosfutebol.com.br \ --header "Authorization: Bearer SUA_API_KEY" ``` ```jsonc Cursor theme={null} // ~/.cursor/mcp.json { "mcpServers": { "dadosfutebol": { "url": "https://mcp.dadosfutebol.com.br", "headers": { "Authorization": "Bearer SUA_API_KEY" } } } } ``` ```jsonc Claude Desktop theme={null} // claude_desktop_config.json — usa o proxy mcp-remote para HTTP { "mcpServers": { "dadosfutebol": { "command": "npx", "args": [ "mcp-remote", "https://mcp.dadosfutebol.com.br", "--header", "Authorization: Bearer SUA_API_KEY" ] } } } ``` ## Chamada direta via HTTP (JSON-RPC) Normalmente é o cliente MCP (Claude, Cursor) que cuida do protocolo. Mas o endpoint MCP aceita chamadas **JSON-RPC 2.0** diretas — útil para depurar a conexão ou integrar de uma linguagem sem um cliente MCP pronto. O transporte HTTP é **stateless**: dá para chamar `tools/call` direto, sem o handshake `initialize`. Envie sempre o header `Authorization: Bearer SUA_API_KEY`. Listar as ferramentas disponíveis: ```bash theme={null} curl -X POST https://mcp.dadosfutebol.com.br \ -H "Authorization: Bearer SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":"1","method":"tools/list"}' ``` Chamar uma tool — os argumentos vão em `params.arguments` (ex.: `obter-campeonato` com `id` 1): ```bash theme={null} curl -X POST https://mcp.dadosfutebol.com.br \ -H "Authorization: Bearer SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": "2", "method": "tools/call", "params": { "name": "obter-campeonato", "arguments": { "id": 1 } } }' ``` O JSON da API vem dentro de `result.content[].text`, como string: ```json theme={null} { "jsonrpc": "2.0", "id": "2", "result": { "content": [ { "type": "text", "text": "{\"data\":{\"id\":3,\"nome\":\"Brasileirão Série A\"}}" } ] } } ``` ## Ferramentas disponíveis São 23 ferramentas, espelhando os endpoints da API v1. IDs (como `campeonato_id`, `time_id`, `partida_id`) costumam vir de uma busca anterior — comece por `listar-campeonatos`, `buscar-times` ou `buscar-jogadores`. ### Campeonatos | Tool | Descrição | Endpoint | | -------------------- | ------------------------------------------------------------------ | ------------------------- | | `listar-campeonatos` | Lista campeonatos; filtros opcionais `temporada`, `status`, `tipo` | `GET /v1/campeonatos` | | `obter-campeonato` | Detalhes de um campeonato (`id`) | `GET /v1/campeonatos/:id` | ### Fases (mata-mata) | Tool | Descrição | Endpoint | | --------------------- | ------------------------------------------------------ | ---------------------------------------------- | | `listar-fases` | Fases de um campeonato (`campeonato_id`) | `GET /v1/campeonatos/:id/fases` | | `obter-fase` | Detalhes de uma fase (`campeonato_id`, `fase_id`) | `GET /v1/campeonatos/:id/fases/:faseId` | | `tabela-da-fase` | Classificação de uma fase (`campeonato_id`, `fase_id`) | `GET /v1/campeonatos/:id/fases/:faseId/tabela` | | `chave-do-campeonato` | Chaveamento de mata-mata (`campeonato_id`) | `GET /v1/campeonatos/:id/chave` | ### Rodadas e partidas | Tool | Descrição | Endpoint | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | `listar-rodadas` | Rodadas e suas partidas (`campeonato_id`) | `GET /v1/campeonatos/:id/rodadas` | | `listar-partidas` | Partidas de um campeonato com filtros (`campeonato_id`, `rodada`, `status`, `time_id`, `data_inicio`, `data_fim`, `pagina`, `por_pagina`) | `GET /v1/campeonatos/:id/partidas` | | `partidas-ao-vivo` | Partidas em andamento agora | `GET /v1/partidas/ao-vivo` | | `eventos-da-partida` | Eventos da partida — gols, cartões e substituições com minuto (`partida_id`) | `GET /v1/partidas/:id/eventos` | | `estatisticas-da-partida` | Estatísticas por lado (`partida_id`) | `GET /v1/partidas/:id/estatisticas` | | `escalacao-da-partida` | Formação, técnico, titulares e reservas (`partida_id`) | `GET /v1/partidas/:id/escalacao` | ### Tabela e artilharia | Tool | Descrição | Endpoint | | ------------------------- | -------------------------------------------------- | ------------------------------------ | | `tabela-de-classificacao` | Classificação do campeonato (`campeonato_id`) | `GET /v1/campeonatos/:id/tabela` | | `artilharia` | Maiores goleadores do campeonato (`campeonato_id`) | `GET /v1/campeonatos/:id/artilharia` | ### Times e jogadores | Tool | Descrição | Endpoint | | ------------------- | ---------------------------------------------------- | ----------------------------- | | `buscar-times` | Busca times por nome (`q`, `tipo`) | `GET /v1/times` | | `jogadores-do-time` | Elenco de um time (`time_id`) | `GET /v1/times/:id/jogadores` | | `buscar-jogadores` | Busca jogadores por nome (`q`, `time_id`, `posicao`) | `GET /v1/jogadores` | | `obter-jogador` | Detalhes de um jogador (`id`) | `GET /v1/jogadores/:id` | ### Conta e ranking FIFA | Tool | Descrição | Endpoint | | ---------------------------- | --------------------------------------------------- | ---------------------------------------------------- | | `meu-plano` | Plano da key e limites/consumo | `GET /v1/me` | | `minhas-estatisticas-de-uso` | Uso da key: requisições, tempo médio, recentes | `GET /v1/perfil/estatisticas` | | `ranking-fifa-selecoes` | Ranking FIFA de seleções (`confederacao`, `limite`) | `GET /v1/estatisticas/fifa/ranking/selecoes` | | `ranking-fifa-selecao` | Histórico FIFA de uma seleção (`time_id`) | `GET /v1/estatisticas/fifa/ranking/selecoes/:timeId` | | `status-da-api` | Saúde da API (público) | `GET /v1/status` | ## Planos e limites As mesmas regras da API REST valem no MCP — veja [Autenticação](/autenticacao) para a tabela completa de planos e limites. Ao chamar uma tool de um recurso fora do seu plano, a resposta vem com erro **"Plano insuficiente"**. Ao estourar a cota de requisições, vem **"Limite atingido"**. Por exemplo, no plano Free as tools `partidas-ao-vivo`, `buscar-times` e `buscar-jogadores` ficam bloqueadas. ## Exemplo de uso Com o servidor conectado, basta pedir em linguagem natural: > "Como está a tabela do Brasileirão Série A?" O assistente chama `listar-campeonatos` para achar o `campeonato_id` da Série A e, em seguida, `tabela-de-classificacao` com esse id — retornando a classificação atualizada direto na conversa. ## Solução de problemas | Sintoma | Causa provável | O que fazer | | ----------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Cliente não conecta ou nenhuma tool aparece | URL incorreta, ou a autorização no navegador não foi concluída | Confirme a URL `https://mcp.dadosfutebol.com.br` (sem parâmetros) e refaça a conexão — o cliente deve abrir o navegador para login e **"Autorizar acesso via MCP"**. | | `401` ao conectar com `?api_key=` na URL | A forma antiga de embutir a chave na URL foi **desativada** | Remova `?api_key=` da URL, deixando só `https://mcp.dadosfutebol.com.br`, e reconecte pelo fluxo OAuth (ou use o header `Authorization` na alternativa programática). | | `403` com `"Sem chave de API ativa"` | A conta autorizou o MCP mas não tem nenhuma API Key ativa | Gere uma chave em `https://dadosfutebol.com.br/api-keys`. | | `401` com `"API Key não fornecida"` (uso programático por header) | Header `Authorization` ausente | Adicione `Authorization: Bearer SUA_API_KEY` na configuração do cliente. | | `401` com `"API Key inválida ou inativa"` | Key incorreta, revogada ou desativada | Valide ou gere uma nova key em `https://dadosfutebol.com.br/api-keys`. | | Tool responde `"Plano insuficiente"` | A ferramenta exige um plano superior ao da sua key | Veja seu plano com `meu-plano` e faça upgrade. No plano Free, tools como `partidas-ao-vivo`, `buscar-times` e `buscar-jogadores` ficam bloqueadas. | | Tool responde `"Limite atingido"` | Cota de requisições do plano esgotada | Aguarde a renovação da cota ou faça upgrade. Acompanhe o consumo com `minhas-estatisticas-de-uso`. | Para um teste rápido de conexão, rode o `curl` de `tools/list`: ele deve retornar a lista das 23 ferramentas. Para diagnosticar bloqueios, use `meu-plano` (plano e limites) e `minhas-estatisticas-de-uso` (consumo atual).