API and MCP setup

MCP server

Streamable HTTP at https://sports-rules.gumballtools.com/api/mcp. No authentication required.

Claude Code

claude mcp add --transport http sports-rules https://sports-rules.gumballtools.com/api/mcp

Claude Desktop or Cursor

{
  "mcpServers": {
    "sports-rules": {
      "type": "http",
      "url": "https://sports-rules.gumballtools.com/api/mcp"
    }
  }
}

Verify it works

curl -X POST 'https://sports-rules.gumballtools.com/api/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

JSON API

Every endpoint accepts GET with query parameters or POST with a JSON body. CORS is open. Full machine-readable description at /.well-known/openapi.json.

# Soccer, IFAB Law 11
curl 'https://sports-rules.gumballtools.com/api/v1/offside?sport=soccer&attacker=40&ball=30\
&secondLastDefender=35&involvement=interfering-with-play'

# An offside position with no involvement -- not an offence
curl 'https://sports-rules.gumballtools.com/api/v1/offside?sport=soccer&attacker=40&ball=30\
&secondLastDefender=35&involvement=none'

# Hockey: a skate in the air is onside since 2021
curl 'https://sports-rules.gumballtools.com/api/v1/offside?sport=hockey&rearSkate=-4&skateOnIce=false'

# The same position when tagging up: not cleared
curl 'https://sports-rules.gumballtools.com/api/v1/offside?sport=hockey&rearSkate=-4&skateOnIce=false\
&situation=tag-up'

Three verdicts, not two: offside, onside, and no-offside-offence. The third is a real and common outcome — in soccer an offside position without involvement in active play is not an offence. For that reason involvement is required rather than defaulted once the geometry makes it decisive: assuming it either way would settle the call on a fact nobody supplied.

Markdown instead of HTML

Every page has a markdown representation at the same canonical URL. Send Accept: text/markdown or append ?format=md. Responses set Vary: Accept. Do not parse the HTML.

curl -H 'Accept: text/markdown' 'https://sports-rules.gumballtools.com/'

Errors

Every failure returns the same shape, with a stable code and a hint describing what to change before retrying.

{
  "error": {
    "code": "invalid_input",
    "message": "...",
    "fix_hint": "...",
    "docs": "https://sports-rules.gumballtools.com/docs"
  }
}