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. 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

Adicione o servidor no seu cliente MCP

Claude Code

claude mcp add --transport http dadosfutebol "https://mcp.dadosfutebol.com.br"

Ou, editando o arquivo de config direto (.claude.json / .mcp.json):

{
  "mcpServers": {
    "dadosfutebol": {
      "type": "http",
      "url": "https://mcp.dadosfutebol.com.br"
    }
  }
}

Autorize no navegador

Ao conectar, o cliente MCP abre o navegador automaticamente. Faça login (ou crie conta) no portal e clique em “Autorizar acesso via MCP”.

Pronto — as tools já aparecem no cliente

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:

https://mcp.dadosfutebol.com.br
Authorization: Bearer SUA_API_KEY

Configuração por cliente (substitua SUA_API_KEY):

claude mcp add --transport http dadosfutebol \
  https://mcp.dadosfutebol.com.br \
  --header "Authorization: Bearer SUA_API_KEY"

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "dadosfutebol": {
      "url": "https://mcp.dadosfutebol.com.br",
      "headers": {
        "Authorization": "Bearer SUA_API_KEY"
      }
    }
  }
}

// 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:

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):

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:

{
  "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 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).

Introdução

Endpoints

Integrações

MCP (IA)

Servidor MCP

Como funciona

Conexão

Alternativa programática (sem navegador)

Chamada direta via HTTP (JSON-RPC)

Ferramentas disponíveis

Campeonatos

Fases (mata-mata)

Rodadas e partidas

Tabela e artilharia

Times e jogadores

Conta e ranking FIFA

Planos e limites

Exemplo de uso

Solução de problemas

​Servidor MCP

​Como funciona

​Conexão

​Alternativa programática (sem navegador)

​Chamada direta via HTTP (JSON-RPC)

​Ferramentas disponíveis

​Campeonatos

​Fases (mata-mata)

​Rodadas e partidas

​Tabela e artilharia

​Times e jogadores

​Conta e ranking FIFA

​Planos e limites

​Exemplo de uso

​Solução de problemas

Servidor MCP

Como funciona

Conexão

Alternativa programática (sem navegador)

Chamada direta via HTTP (JSON-RPC)

Ferramentas disponíveis

Campeonatos

Fases (mata-mata)

Rodadas e partidas

Tabela e artilharia

Times e jogadores

Conta e ranking FIFA

Planos e limites

Exemplo de uso

Solução de problemas