Hand of the King Wiki
MCP API Calls

MCP API Calls

HOTK MCP access has two layers: MCP tools used by the external client and delegated HOTK API routes used by the MCP server.

Endpoint

Hosted MCP endpoint:

POST https://mcp.hotk.dev/mcp
Authorization: Bearer hotk_ag_...
Accept: application/json, text/event-stream
Content-Type: application/json

GET /mcp returning 405 is expected. MCP clients initialize and call tools over authenticated POST /mcp.

MCP Tools

hotk_campaign_snapshot

Reads the campaign and kingdom state needed for advice.

Use it when the agent needs the current campaign state before making recommendations.

Expected backing scopes:

  • campaign:read

Expected backing routes:

  • GET /api/v1/agent/campaigns/{campaignID}
  • GET /api/v1/agent/campaigns/{campaignID}/king/status
  • GET /api/v1/agent/campaigns/{campaignID}/king/status/full
  • GET /api/v1/agent/campaigns/{campaignID}/king/stats
  • GET /api/v1/agent/campaigns/{campaignID}/king/resources/status
  • GET /api/v1/agent/campaigns/{campaignID}/king/treasury/status
  • GET /api/v1/agent/campaigns/{campaignID}/king/trade/routes

hotk_list_actions

Lists active docket items and available royal actions.

Use it when the agent needs to compare current choices.

Expected backing scopes:

  • actions:list

Expected backing routes:

  • GET /api/v1/agent/campaigns/{campaignID}/king/docket/items
  • GET /api/v1/agent/campaigns/{campaignID}/king/actions

hotk_propose_action

Submits a recommendation for the human/site to review. It does not execute the recommendation.

Expected backing scope:

  • actions:propose

Backing route:

  • POST /api/v1/agent/campaigns/{campaignID}/proposals

Typical proposal body:

{
  "kind": "docket_option",
  "action": "resolve_docket",
  "item_id": "docket-item-id",
  "option_index": 0,
  "rationale": "This protects legitimacy while keeping enough treasury for the next tick.",
  "payload": {
    "confidence": 0.72,
    "risk": "medium"
  }
}

Allowed proposal kinds:

  • recommendation
  • docket_option
  • royal_action
  • tick_advance
  • note

Browser Grant Handshake Routes

These routes are called by the authenticated web app, not by the external MCP client with an agent grant.

Create Connection

POST /api/v1/campaigns/{campaignID}/agent-connections

Purpose: creates a pending campaign-scoped connection request.

Auth: normal player/browser auth with king scope.

Common request fields:

  • mode
  • duration_minutes
  • scopes
  • client_id
  • client_name
  • client_redirect_uri
  • code_challenge
  • code_challenge_method
  • state
  • nonce

Get Connection Consent

GET /api/v1/agent-connections/{connectionToken}

Purpose: returns pending connection details to the owning player.

Auth: normal player/browser auth.

Approve Connection

POST /api/v1/agent-connections/{connectionToken}/approve

Purpose: approves the pending connection and returns exchange data.

Auth: normal player/browser auth.

Common request fields:

  • duration_minutes
  • scopes
  • max_actions
  • max_ticks

For Advisor mode, execution budgets should stay absent or zero because the advisor cannot execute.

Exchange Connection

POST /api/v1/agent-connections/exchange

Purpose: exchanges the approved one-time connection data for the hotk_ag_... grant token.

Auth: public exchange endpoint using the connection token and exchange code, not the user's Supabase session.

Typical request body:

{
  "connection_token": "...",
  "exchange_code": "...",
  "client_id": "external-agent-name"
}

The grant token is shown once. Store it in the MCP client configuration, not in browser code.

Account Grant Routes

These routes are for the player dashboard.

List Grants

GET /api/v1/agent-grants

Purpose: lists active and historical grants visible to the current user.

Revoke Grant

POST /api/v1/agent-grants/{grantID}/revoke

Purpose: revokes one grant.

Revoke All Grants

POST /api/v1/agent-grants/revoke-all

Purpose: revokes all grants for the current user.

List Campaign Proposals

GET /api/v1/campaigns/{campaignID}/agent-proposals

Purpose: lists advisor proposals for a campaign owned by the current user.

Delegated-Agent Routes

Delegated-agent routes live under:

/api/v1/agent/campaigns/{campaignID}

They accept Authorization: Bearer hotk_ag_... only when the grant is active, campaign-matched, and has the required scope.

campaign:read

  • GET /
  • GET /king/status
  • GET /king/status/full
  • GET /king/stats
  • GET /king/resources/status
  • GET /king/treasury/status
  • GET /king/trade/routes

actions:list

  • GET /king/docket/items
  • GET /king/actions

actions:propose

  • POST /proposals

Common Errors

401 missing agent grant

The request did not include a usable bearer grant token.

Check:

  • header is Authorization: Bearer hotk_ag_...
  • token is being sent to mcp.hotk.dev, not hotk.dev
  • token was copied before page reload

403 agent grant denied

The token is expired, revoked, unknown, or malformed.

403 agent grant campaign mismatch

The token belongs to another campaign.

403 agent grant scope denied

The grant does not include the scope required by that delegated route.

Normal API route rejects agent token

Expected. Agent grants are intentionally rejected by normal HOTK auth. Only explicit delegated-agent routes accept them.