Tool reference

The Scorelytics MCP server exposes eight tools. Inputs and outputs are JSON Schema; the agent calls them via JSON-RPC 2.0.

All examples below use the tools/call JSON-RPC method. Run them with:

curl https://api.scorelytics.pro/v1/mcp \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '<json-rpc body>'

---

list_leagues

List every tracked league.

Input — none.

Output — JSON array of { id, country, name, season, sport, logo_url }.

{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": { "name": "list_leagues" }
}

---

get_matches

Query matches with optional filters.

Input:

Field	Type	Notes
date	string	"YYYY-MM-DD" UTC, or "today" / "yesterday" / "tomorrow". Omit for today.
league_id	string	League ID from list_leagues.
status	string	"scheduled", "live", "finished".
limit	integer	1–50, default 20.

Output — list of compact match records, each with id, teams, score, half-time score, status, kickoff time, league name and country.

{
  "jsonrpc": "2.0", "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_matches",
    "arguments": { "status": "live", "limit": 10 }
  }
}

---

get_match

Full record for one match.

Input:

Field	Type	Required
match_id	string	yes

Output — match detail with score, half-time score, period, minute, game clock (basketball), formations, referee, venue, attendance, timestamps, plus a localized period label ("Q1", "1st Half"…).

---

get_match_events

Chronological event timeline.

Input: { match_id }.

Output — list of { type, team, minute, added_time, player, player_in }, sorted by minute then added time.

---

get_match_stats

In-game statistics.

Input: { match_id }.

Output — list of stat entries grouped by section ("Match", "1st Half"…). Football examples: ball possession, shots on target, corners, fouls. Basketball examples: FG%, 3P%, rebounds, assists.

---

get_match_lineups

Starting XI and bench.

Input: { match_id }.

Output — { home: { starters, substitutes }, away: { starters, substitutes } }. Each player carries name, jersey number, position and country.

---

get_standings

Current league standings.

Input: { league_id }.

Output — standings table with rank, team name, played, won, drawn, lost, goals for / against, goal difference, points.

---

get_head_to_head

Recent meetings between the two teams of a given match.

Input: { match_id }.

Output — last 20 head-to-head matches with date, both teams, score and status.

---

Error semantics

When a tool fails, the response carries a regular MCP tool_result with isError: true and a human-readable message:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "match \"abc999\" not found" }],
    "isError": true
  }
}

Standard JSON-RPC errors (-32601 method not found, -32602 invalid params, etc.) appear in the error field instead.