Skip to main content

​
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.
O servidor MCP usa a mesma API Key da API REST e respeita exatamente os mesmos planos e limites de requisições. 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. 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 autenticação é por Bearer Token — a mesma key da API REST. Solicite a sua em https://dadosfutebol.com.br/api-keys.

​
URL com a chave (mais simples)

A forma mais rápida — e que evita o fluxo de OAuth de alguns clientes — é embutir a API Key na própria URL, em ?api_key=:
Claude Code
claude mcp add --transport http dadosfutebol \
  "https://api.dadosfutebol.com.br/mcp/v1?api_key=SUA_API_KEY"
Ou, editando o arquivo de config direto (.claude.json / .mcp.json): 
{
  "mcpServers": {
    "dadosfutebol": {
      "type": "http",
      "url": "https://api.dadosfutebol.com.br/mcp/v1?api_key=SUA_API_KEY"
    }
  }
}
Não quer montar a URL na mão? Acesse https://dadosfutebol.com.br/api-keys, entre com sua conta, escolha uma das suas chaves no painel “Conectar via MCP” e copie a URL, o comando ou o JSON já prontos.
A URL sem ?api_key= (e sem header Authorization) faz o cliente tentar OAuth e falhar com HTTP 404 / Invalid OAuth error response. Sempre inclua a chave na URL ou no header.
A chave fica visível na URL — trate-a como uma senha e não a compartilhe. Se preferir mantê-la fora da URL, use o método por header Authorization abaixo.

​
HTTP por header

Aponte seu cliente MCP para o endpoint abaixo e envie a API Key no header Authorization: 
https://api.dadosfutebol.com.br/mcp/v1
Authorization: Bearer SUA_API_KEY
Configuração por cliente (substitua SUA_API_KEY): 
claude mcp add --transport http dadosfutebol \
  https://api.dadosfutebol.com.br/mcp/v1 \
  --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/v1 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: 
curl -X POST https://api.dadosfutebol.com.br/mcp/v1 \
  -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): 
curl -X POST https://api.dadosfutebol.com.br/mcp/v1 \
  -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: 
{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "content": [
      { "type": "text", "text": "{\"data\":{\"id\":1,\"nome\":\"Campeonato Brasileiro 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

ToolDescriçãoEndpoint
listar-campeonatosLista campeonatos; filtros opcionais temporada, status, tipoGET /v1/campeonatos
obter-campeonatoDetalhes de um campeonato (id)GET /v1/campeonatos/:id

​
Fases (mata-mata)

ToolDescriçãoEndpoint
listar-fasesFases de um campeonato (campeonato_id)GET /v1/campeonatos/:id/fases
obter-faseDetalhes de uma fase (campeonato_id, fase_id)GET /v1/campeonatos/:id/fases/:faseId
tabela-da-faseClassificação de uma fase (campeonato_id, fase_id)GET /v1/campeonatos/:id/fases/:faseId/tabela
chave-do-campeonatoChaveamento de mata-mata (campeonato_id)GET /v1/campeonatos/:id/chave

​
Rodadas e partidas

ToolDescriçãoEndpoint
listar-rodadasRodadas e suas partidas (campeonato_id)GET /v1/campeonatos/:id/rodadas
listar-partidasPartidas 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-vivoPartidas em andamento agoraGET /v1/partidas/ao-vivo
eventos-da-partidaEventos da partida (partida_id) — indisponível (501)GET /v1/partidas/:id/eventos
estatisticas-da-partidaEstatísticas por lado (partida_id)GET /v1/partidas/:id/estatisticas
escalacao-da-partidaFormação, técnico, titulares e reservas (partida_id)GET /v1/partidas/:id/escalacao

​
Tabela e artilharia

ToolDescriçãoEndpoint
tabela-de-classificacaoClassificação do campeonato (campeonato_id)GET /v1/campeonatos/:id/tabela
artilhariaMaiores goleadores do campeonato (campeonato_id)GET /v1/campeonatos/:id/artilharia

​
Times e jogadores

ToolDescriçãoEndpoint
buscar-timesBusca times por nome (q, tipo)GET /v1/times
jogadores-do-timeElenco de um time (time_id)GET /v1/times/:id/jogadores
buscar-jogadoresBusca jogadores por nome (q, time_id, posicao)GET /v1/jogadores
obter-jogadorDetalhes de um jogador (id)GET /v1/jogadores/:id

​
Conta e ranking FIFA

ToolDescriçãoEndpoint
meu-planoPlano da key e limites/consumoGET /v1/me
minhas-estatisticas-de-usoUso da key: requisições, tempo médio, recentesGET /v1/perfil/estatisticas
ranking-fifa-selecoesRanking FIFA de seleções (confederacao, limite)GET /v1/estatisticas/fifa/ranking/selecoes
ranking-fifa-selecaoHistórico FIFA de uma seleção (time_id)GET /v1/estatisticas/fifa/ranking/selecoes/:timeId
status-da-apiSaúde da API (público)GET /v1/status

​
Planos e limites

As mesmas regras da API REST valem no MCP — veja Autenticação 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.
A tool eventos-da-partida está temporariamente indisponível e responde 501 em qualquer plano — o schema permanece para reativação futura.

​
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

SintomaCausa provávelO que fazer
Cliente não conecta ou nenhuma tool apareceURL incorreta ou header Authorization ausenteConfirme a URL https://api.dadosfutebol.com.br/mcp/v1 e o header Authorization: Bearer SUA_API_KEY. Teste com o curl de tools/list acima.
HTTP 404 / Invalid OAuth error response ao conectarServidor adicionado sem autenticação — o cliente tentou descobrir OAuth (/.well-known/...), que não existeReconfigure usando a URL com a chave (?api_key=SUA_API_KEY) ou o header Authorization: Bearer SUA_API_KEY. Pegue a URL pronta em https://dadosfutebol.com.br/api-keys.
401 com "API Key não fornecida"Header Authorization ausenteAdicione Authorization: Bearer SUA_API_KEY na configuração do cliente.
401 com "API Key inválida ou inativa"Key incorreta, revogada ou desativadaValide 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 keyVeja 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 esgotadaAguarde a renovação da cota ou faça upgrade. Acompanhe o consumo com minhas-estatisticas-de-uso.
eventos-da-partida responde 501Ferramenta temporariamente indisponívelSem ação — o recurso está desativado de propósito; o schema permanece para reativação futura.
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).