Soccerverse MCP

This page documents the Soccerverse MCP server.

#Purpose

The Soccerverse MCP server exposes read-only Soccerverse game data as MCP tools for AI clients: clubs, players, users, markets, fixtures, transfers, votes, shop data, and analytics/leaderboards. The server wraps three upstream source families:

• Datacentre REST API: https://services.soccerverse.com/api
• GSP JSON-RPC API: https://services.soccerverse.com/gsp/
• Democrit/shop GraphQL subgraphs: configured by DEMOCRIT_GRAPHQL_URL and SHOP_GRAPHQL_URL

The implementation is a FastAPI server with Streamable HTTP MCP support. Public production endpoint:

https://mcp.soccerverse.io/mcp

Local/dev examples can use the same path on their configured host, for example http://localhost:8928/mcp.

Endpoints:

• POST /mcp - spec-compliant Streamable HTTP MCP endpoint.
• GET /mcp - optional keepalive SSE stream.
• POST /sse - legacy JSON-RPC-over-HTTP endpoint.
• GET /sse - legacy long-lived SSE stream.
• GET /health - server health.

#Legacy /sse compatibility

/sse is not the current Streamable HTTP MCP endpoint, but it is still useful for older GPT/Claude Desktop/CLI-style integrations that expect server-sent events.

curl -N https://mcp.soccerverse.io/sse

Use /mcp for new integrations unless a client specifically requires SSE.

#Access and auth notes

The MCP server supports optional bearer auth on /mcp and /sse. If MCP_AUTH_TOKEN is set, clients must send:

curl -H "Authorization: Bearer $MCP_AUTH_TOKEN" http://localhost:8928/health

Do not put real tokens in docs, logs, examples, shell history, or screenshots. Use placeholders such as $CLOUDFLARE_BYPASS_SECRET and $MCP_AUTH_TOKEN only.

#MCP calling shape

A generic MCP tool call over Streamable HTTP looks like this:

# Production/public endpoint shape:
curl -sS https://mcp.soccerverse.io/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_club_details",
      "arguments": {"club_id": 50}
    }
  }'

# Local/dev equivalent:
curl -sS http://localhost:8928/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

The server returns a JSON-RPC envelope. Tool handlers wrap final payloads in MCP content blocks: {"content":[{"type":"text","text":"..."}]}.

Tool discovery:

curl -sS http://localhost:8928/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

#Money scaling note

Raw money and influence-price integers from Soccerverse APIs are scaled by MONETARY_DIVISOR = 10000. MCP handlers should use utils.to_svc(), utils.to_svc_short(), and utils.to_svc_str() rather than hand-rolled conversion.

Example: raw 123456789 means 12,345.6789 SVC before display rounding. Many transformed MCP responses include human strings plus _short companion fields.

#Notes

• Country ids are 3-letter ISO strings such as ENG, ESP, DEU; never numeric country codes.
• Divisions are user-facing 1-based in MCP tools, while some upstream APIs store them 0-based. Use the transformation helpers.
• GSP responses can be wrapped in a blockchain envelope. Handlers must unwrap with extract_blockchain_data() before processing.
• Fixture timestamps usually use date as unix seconds, not timestamp.
• League names from the rincon pack are keyed by internal ids, not public league_id values.
• share_type must be explicit for share-balance tools: club, player, or all.
• get_messages and transfer-count REST source calls require season_id even where the MCP schema text describes it as optional; use get_seasons first.
• get_all_transfer_history is in MCP as a GSP-oriented tool but direct GSP currently returned METHOD_NOT_FOUND; use the Datacentre transfer-history path through MCP handlers/source where possible.

#Tool domains

#Name resolution

Purpose: fuzzy name-to-id lookup using the rincon pack cache (.cache/svpack_v2.json) and rapidfuzz.

Upstream/source: local pack data loaded by name_resolver.py, routed via handlers/name_resolution.py.

Tools:

Example MCP call:

{
  "name": "resolve_club_name",
  "arguments": { "name": "Manchester United", "limit": 5 }
}

Response notes: ranked matches with ids and confidence scores. Treat fuzzy matches as candidates, not proof.

#Clubs

Purpose: retrieve club details, club lists, job postings, squads, schedules, tactics, fixtures, league membership, history, balance sheets, messages, loans, transfers, and tactical analysis.

Upstream/source: Datacentre REST for club facts/history/dumps; GSP JSON-RPC for schedule, fixtures, tactics, votes, and shares; composite analysis in handlers/analysis.py.

Tools:

Example:

curl -sS 'https://services.soccerverse.com/api/clubs/detailed?club_id=50&per_page=5'

Example GSP call:

curl -sS 'https://services.soccerverse.com/gsp/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"get_club_schedule","params":{"club_id":50,"season_id":2}}'

Example MCP tool call:

{
  "name": "get_club_details",
  "arguments": { "club_id": 50 }
}

Response notes: REST club records include balance, fans_current, stadium_size_current, manager_name, default_formation, transfers_in/out, country/division fields, and share/market values. GSP fixture rows include fixture_id, turn_id, date, home/away clubs, goals, comp metadata, and played.

#Players

Purpose: search players and retrieve details, payouts, transfer/loan/morale/history, competition statistics, squad membership, and player ROI analytics.

Upstream/source: Datacentre REST for player details/history/dumps; GSP JSON-RPC for payouts and competition data.

Tools:

Example:

curl -sS 'https://services.soccerverse.com/api/players/detailed?player_id=1100&per_page=5'

Example GSP call:

curl -sS 'https://services.soccerverse.com/gsp/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"get_player_payouts","params":{"player_id":1100}}'

Example MCP tool call:

{
  "name": "get_player_details",
  "arguments": { "player_id": 1100 }
}

Response notes: player detail records include availability (fitness, injured, banned in some GSP shapes), ratings (rating_gk, rating_tackling, rating_passing, etc.), position fields, wages, contract, morale, and club/agent context. Money-like values follow the 10,000 raw-int divisor.

#Users and managers

Purpose: inspect user profiles, trading stats, activity, balance sheets, achievements, rankings, referrals, manager history, and manager competition history.

Upstream/source: Datacentre REST for user details/activity/leaderboards/achievements; GSP for manager and competition history.

Tools:

Example:

curl -sS 'https://services.soccerverse.com/api/users/detailed?names=snailbrain&per_page=5'

Example MCP tool call:

{
  "name": "get_user_details",
  "arguments": { "username": "snailbrain" }
}

Response notes: user detail records include name, balance, last-active timestamps, managed club_id, trade volume fields, and milestone trade dates. Keep personally sensitive details out of examples unless already public and necessary.

#Market and shares

Purpose: inspect world market data, share balances, trading graphs/history, orderbooks, user orders, top traders, rich lists, SVC trades, and pre-aggregated order dumps.

Upstream/source: Datacentre REST for market/share history and dumps; GSP for orderbooks/orders/votes; Democrit GraphQL for SVC trades.

Tools:

| Tool | Key params | Upstream | Notes | | -------------------------------- | ------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------- | ------------------------------------------------- | | get_market_data | none | REST /market | Game-wide market/population/activity stats. | | get_trading_graph | club_id or player_id, time_range | REST /trading_graph | Price/time data. | | get_share_trade_history | name, club_id, player_id, sorting, page | REST /share_trade_history | At least one filter. | | get_share_balances | share_type, plus club_id/player_id/name/aggregation filters | REST /share_balances | Always set share_type. | | get_share_balance_by_user_club | user_id, club_id | REST /share_balance_by_user_club | User/club holding. | | get_user_share_orders | name | GSP | Active bid/ask orders by user. | | get_share_orderbook | share | GSP | Use club_<id> or player_<id> in MCP. | | get_top_traders | none | REST /users/detailed sorted by volume | Top active influence traders. | | get_svc_trades_summary | none | Democrit GraphQL | Recent SVC exchange trades. | | get_share_orders_dump | share_type, share_ids | REST /dumps/share_orders/{clubs | players} | Bulk orderbook dump, refreshed about every 2 min. |

Example:

curl -sS 'https://services.soccerverse.com/api/share_balances?club_id=50&share_type=club&per_page=5'

Example dump call:

curl -sS 'https://services.soccerverse.com/api/dumps/share_orders/clubs?ids=50'

Example MCP tool call:

{
  "name": "get_share_balances",
  "arguments": { "club_id": 50, "share_type": "club", "page": 1 }
}

Response notes: share balances include user/share ids, num, last_price, country/league/division, and manager/agent names where available. Orderbook dumps return {meta, data}; data is keyed by share id.

#Fixtures, competitions, leagues, and reference data

Purpose: discover seasons, countries, leagues, league tables, cups, associations, fixtures, match events/commentary, match player data, and recent competitions.

Upstream/source: Datacentre REST for countries/leagues/tables/commentary/history; GSP JSON-RPC for fixtures, turns, cups, associations, and competition stats.

Tools:

Example:

curl -sS 'https://services.soccerverse.com/api/league_tables?country_id=ENG&division=1&per_page=5'

Example GSP call:

curl -sS 'https://services.soccerverse.com/gsp/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"get_seasons","params":{}}'

Example MCP tool call:

{
  "name": "get_league_tables",
  "arguments": { "country_id": "ENG", "division": 1 }
}

Response notes: league-table rows include club_id, league_id, manager_name, country/division, played/won/drawn/lost, goals, points, form, season id, stadium and fanbase fields.

#Transfers

Purpose: inspect active transfer auctions, club/player transfer history, auction details, transfer counts, and recent completed moves.

Upstream/source: GSP JSON-RPC for current auctions; Datacentre REST for historical transfer data and counts.

Tools:

Example GSP call:

curl -sS 'https://services.soccerverse.com/gsp/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"get_top_transfer_auctions","params":{"num":5}}'

Example REST call:

curl -sS 'https://services.soccerverse.com/api/transfers/counts?club_id=50&season_id=2'

Example MCP tool call:

{
  "name": "get_top_transfer_auctions",
  "arguments": { "num": 5 }
}

Response notes: auction rows include transfer_auction_id, player_id, club_id, minimum_bid, high_bid, rating, position, age/date fields, and status flags.

#Votes

Purpose: inspect active votes/proposals globally, by shareholder, or by club/player share.

Upstream/source: GSP JSON-RPC via handlers/gsp_other.py.

Tools:

Example GSP call:

curl -sS 'https://services.soccerverse.com/gsp/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"get_votes_for_shareholder","params":{"name":"snailbrain"}}'

Example MCP tool call:

{
  "name": "get_votes_for_shareholder",
  "arguments": { "name": "snailbrain" }
}

Response notes: vote rows include share, type, state, start_time, and end_time. Share payloads may identify club/player shares; transform to names when resolver data is available.

#Shop

Purpose: inspect Soccerverse pack purchases and club sale/tranche status.

Upstream/source: shop GraphQL subgraph configured by SHOP_GRAPHQL_URL, implemented in shop_api.py and handlers/shop.py.

Tools:

Example MCP tool call:

{
  "name": "get_sale_clubs",
  "arguments": { "club_id": 50, "limit": 5 }
}

Response notes: shop purchase rows include timestamp, receiver, numPacks, usdSpent, primaryClub, and tier. Sale-club rows include clubId, minted, remainingInTranche, trancheIndex, tier, and pausedInTier.

#Analytics and leaderboards

Purpose: retrieve aggregate market stats, earnings leaderboards, ROI/payback analytics, tactical analysis, rich/best-manager/top-trader lists, referrals, and ticker data.

Upstream/source: Datacentre REST /market, /ticker, /leaderboards/*, /dumps/*; Democrit GraphQL; composite analysis code.

Tools:

Example:

curl -sS 'https://services.soccerverse.com/api/market'

Example dump call:

curl -sS 'https://services.soccerverse.com/api/dumps/player_earnings?threshold=5&limit=5'

Example MCP tool call:

{
  "name": "get_player_earnings",
  "arguments": { "threshold": 5, "limit": 5, "sort": "payback" }
}

Response notes: dump endpoints generally return a {meta, data} envelope. Preserve meta.fields in final docs when examples are expanded.