# Kingshot Alliance Command — API and MCP Server

Kingshot Alliance Command has a free Model Context Protocol (MCP) server for AI agents and developers. It gives the same Kingshot reference data and upgrade cost calculators as the website: heroes, Masters, items, events, the hero tier list, and Governor Gear, Governor Charm, Truegold, hero shard, and Mastery Forging costs. With a user's permission, it can also read that player's own profile, goals, and inventory.

- Developer page: https://www.kingshotcommand.com/developers
- OpenAPI spec: https://www.kingshotcommand.com/openapi.json
- MCP server card: https://www.kingshotcommand.com/.well-known/mcp/server-card.json
- Agentic Resource Discovery catalog: https://www.kingshotcommand.com/.well-known/ard.json
- Site guide for agents: https://www.kingshotcommand.com/llms.txt

## Endpoints

Both endpoints speak MCP over Streamable HTTP and are stateless: each `POST` carries one JSON-RPC 2.0 message and gets a plain JSON response. Send `Accept: application/json, text/event-stream`.

| Endpoint | Access |
| --- | --- |
| `https://api.kingshotcommand.com/mcp` | Public, read-only. No account or API key. |
| `https://api.kingshotcommand.com/mcp/account` | The public tools plus the signed-in player's own data. Needs an OAuth 2.1 bearer token. |

## Quickstart

Add the public server to any MCP client, for example in a `.mcp.json` file:

```json
{
  "mcpServers": {
    "kingshot": {
      "type": "http",
      "url": "https://api.kingshotcommand.com/mcp"
    }
  }
}
```

Or call a tool directly:

```bash
curl -X POST https://api.kingshotcommand.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "governor_gear_cost",
      "arguments": { "from": "Gold ★0", "to": "Gold T2 ★3" }
    }
  }'
```

Tool results come back in `result.content` as text holding JSON. Call `tools/list` for every tool's input schema.

## Tools

Every tool is read-only. The cost tools and `get_hero` also return MCP Apps views (`ui://kingshot/...`) for clients that render them.

| Tool | What it returns |
| --- | --- |
| `search_database` | Heroes, Masters, items, and events matching a name, with each match's key and page URL. |
| `get_hero` | A hero's skills, buff values, and exclusive gear. |
| `get_master` | A Master's skills, talent, and relationship levels. |
| `get_item` | An item and the events that grant it. |
| `get_event` | An event, its rewards, and guides. |
| `get_tier_list` | The curated S–D hero tier list for a role and generation. |
| `governor_gear_cost` | Materials to upgrade a Governor Gear piece between levels. |
| `governor_charm_cost` | Charm Guides and Designs between two charm levels. |
| `truegold_upgrade_cost` | Truegold and Tempered Truegold for the TG1–TG8 chain. |
| `hero_shards_cost` | Hero shards between two star and tier levels. |
| `mastery_forging_cost` | Forgehammer, Mithril, and Mythic Gear for Mastery Forging and Red Gear Ascension. |

On `/mcp/account` only:

| Tool | What it returns |
| --- | --- |
| `get_my_profile` | The signed-in player's saved profile: Town Center level, power, troops, combat stats, and heroes. |
| `get_my_goals` | Their active Progression Goals, with remaining materials and inventory readiness. |
| `get_my_inventory` | The materials saved in their inventory, by section. |

## Authentication

The public endpoint needs no authentication. The account endpoint uses OAuth 2.1: authorization code flow with PKCE (S256 only) and dynamic client registration (RFC 7591), so there's no API key to request. The user signs in and approves your app on a consent page that lists exactly what it can read.

A request without a valid token gets a `401` whose `WWW-Authenticate` header points at the discovery documents:

- Protected resource metadata (RFC 9728): https://api.kingshotcommand.com/.well-known/oauth-protected-resource/mcp/account
- Authorization server metadata (RFC 8414): https://api.kingshotcommand.com/.well-known/oauth-authorization-server

## Scopes

Any token the user approves gives the same fixed, read-only access: their profile, active goals, and saved inventory. It can't change anything in the account, read alliance data, or spend AI Credits. The scopes only control what goes into the ID token and whether you get a refresh token.

| Scope | Effect |
| --- | --- |
| `openid` | Signs the user in. Enough to call the account MCP server; request only this for least privilege. |
| `offline_access` | Issues a refresh token so the client stays connected. |
| `profile` | Adds the account name to the ID token. |
| `email` | Adds the email address to the ID token. No tool needs it. |

## Rate limits

60 requests per minute, per client on `/mcp` and per user on `/mcp/account`. Going over returns `429` with `{"code": "RATE_LIMITED"}`.

## Retries

Every tool is read-only, so any request can be retried safely: a retry never creates, changes, or charges anything. An optional `Idempotency-Key` header is accepted.

## Versioning and deprecation

- The protocol is versioned by the `MCP-Protocol-Version` header, negotiated in `initialize`. Supported: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, and `2024-10-07`. Any other version gets a `400`.
- Tools are versioned with the server (`serverInfo.version`). Adding a tool, or an optional argument or result field, isn't a breaking change.
- Before a breaking change (a tool removed or renamed, a required argument added, a result field removed), affected responses carry a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) with a date at least 90 days later, and the change is listed on the developer page.

## In the browser (WebMCP)

In browsers that support WebMCP, the website registers in-page tools: `search_database`, `get_page_markdown`, `get_site_guide`, and `open_page`. Every page listed in the sitemap also returns Markdown when requested with `Accept: text/markdown`.

## Support

Questions or bugs: https://www.kingshotcommand.com/contact