# Connect an assistant to Auction House FYI

Use **`https://auctionhouse.fyi/mcp`** to ask about WoW: Forever prices, compare markets, show charts and manage your own watchlist, alerts and saved boards. It is a remote MCP server using Streamable HTTP. You do not need a local server or the desktop companion to query it.

The [MCP contract](../protocol/mcp-v1.md) defines the transport, tools and UI metadata; the [API contract](../protocol/api-v1.md) defines the underlying market facts. The same entitlement table controls both. Host setup below follows official documentation checked on 2026-09-30. Completing a local test does not establish that a connector has been deployed, authenticated in a real account or accepted into a host's public directory.

## Research desk expansion (2026-10-08)

The branch adds a research workspace with item dossiers, 2,521 client-table recipes, three client questlines, six reviewed MIT community quest references and five reported quest starts. `get_recipe_cost` estimates material costs from tier-aware observations; missing prices keep the total unknown. Client references are `unverified-forever`; community records are `historical-reference`. Neither is independently verified gameplay. Possible reward IDs are not guaranteed rewards, and reported starts are not objectives or item drop locations.

Use `search_knowledge`, `get_recipe`, `get_recipe_cost`, `get_questline`, `search_quests`, `get_quest`, `search_atlas` and `get_item_locations`. `render_knowledge` and `render_quests` open the same interactive desk. The shared atlas includes 56 maps and 574 approximate area-label anchors; these identify geography, not NPC spawns. The [source research](research/2026-10-08-forever-knowledge-sources.md), [knowledge contract](../protocol/knowledge-v1.md) and [atlas contract](../protocol/atlas-v1.md) describe rights, evidence and current coverage. Regenerate the public catalogue with `node scripts/gen-atlas-knowledge.mjs` after either input changes; its version hashes the combined sources and records.

The desk negotiates fullscreen, sends explicit questions to the conversation, opens host-mediated links and accepts validated selection/deep-link context. Unsupported hosts retain ordinary JSON tools. Desktop item mentions resolve through public catalogue resources. Host capabilities determine which controls appear; local protocol/browser tests do not prove support in a particular ChatGPT account. The [extensions research](research/2026-10-08-chatgpt-extensions.md) documents the current compatibility matrix, including why the pinned MCP v2 packages are retained instead of adding the extensions package's incompatible v1 peers.

The private plugin package lives in [docs/plugin/auctionhouse-fyi](plugin/auctionhouse-fyi), with onboarding and research skills. Its portable schemas have been validated; it has not been published or verified in a real ChatGPT host. The [implementation plan](design/2026-10-08-chatgpt-research-desk-plan.md) records native preferences, rich decisions and portable research documents as later milestones.

Market monitoring adds authenticated `alert.triggered` subscriptions through [MCP Events](../protocol/mcp-events-v1.md). Delivery uses existing saved alerts, current alert entitlements, signed callbacks, bounded retries and subscriptions capped at 24 hours and the OAuth token's lifetime. Reconnect/resubscribe after expiry. This is a server implementation awaiting a real Work conversation test; callback hosts stay restricted until the actual host is observed. No automatic wakeup is claimed yet. The desk's My alerts view reads existing private alerts and watchlists after an explicit click.

Local verification on 2026-10-08 passed all 18 repository check stages. Chromium exercised the running local Worker's reference tools in an MCP Apps test host at desktop and mobile widths, in dark and light themes. Recipe search, quest search, empty results, source links, focus mode and explicit conversation questions passed with no console errors, failed requests or horizontal overflow. HTTP checks also confirmed unknown material costs and locations, possible quest rewards, and refusals for anonymous monitoring and private reads. Search uses explicit button and Enter-key handlers because a sandbox with only `allow-scripts` blocks native form submission. The host bridge was simulated; CI preview journeys, live market rendering and real ChatGPT OAuth/callback/wakeup remain separate checks.

## Choose your access

| Capability | Anonymous | Signed-in free | Contributor or premium |
| --- | --- | --- | --- |
| Item search, metadata, prices and overall quantity | Hourly view | Hourly view | Latest observed data |
| Daily and hourly charts | Up to 7 days; finished hours | Up to 7 days; finished hours | Daily up to 90 days; hourly up to 14 days |
| Minute charts | — | — | Up to 72 hours; default 24 hours |
| Order books and per-level depth | — | — | Yes |
| Estimated listed, sold and expired volume | — | — | Yes |
| Watchlist | — | 20 items | 200 items |
| Create, edit and delete alerts | — | — | 100 alerts |
| Save boards | — | — | 20 dashboards |
| Request limit per minute | 60 | 120 | 600 |

Roles are a set: contributor and premium both grant these deeper market features, and a person can have both. Contributor access lasts seven days after a credited scan. Signed-in accounts can still read their existing settings after access expires; writes and alert evaluation need the current feature. Limits come from [shared/src/entitlements.ts](../shared/src/entitlements.ts), rather than a separate MCP subscription.

Ask the assistant to call `get_access` before using account tools. It reports the caller's current features and limits. Signing in does not automatically grant order books or alerts. API keys require API access for market reads; OAuth also supports free accounts.

## Claude Code

Add the public server:

```sh
claude mcp add --transport http auctionhouse-fyi https://auctionhouse.fyi/mcp
claude mcp get auctionhouse-fyi
```

Then ask: “Find Runecloth in Normal Alliance and show its price and listed quantity, with the observation time.” Public questions work anonymously. To use account tools, open `/mcp`, select Auction House FYI and authenticate through the browser. Use your Auction House FYI account; the MCP server does not need your Claude password. See [Claude Code's official MCP setup and authentication guide](https://code.claude.com/docs/en/mcp).

A contributor or premium account can alternatively supply its API key. Prefer a client configuration that expands an environment variable, instead of pasting the key into a committed file:

```json
{
  "mcpServers": {
    "auctionhouse-fyi": {
      "type": "http",
      "url": "https://auctionhouse.fyi/mcp",
      "headers": { "Authorization": "Bearer ${AHF_KEY}" }
    }
  }
}
```

Set `AHF_KEY` in the client environment before starting Claude Code. Keep it out of Lua, prompts, URLs and source control. Create and revoke keys on the website's account page. API-key access and contributor expiry follow the existing API rules.

## Claude and Claude Desktop

In **Customize → Connectors**, add a custom remote connector with the MCP URL above, then connect your account when prompted. Enable it for the conversation. A Team or Enterprise owner may need to add the connector for the organization first. These steps use the remote connector flow, including on Claude Desktop; they do not require a local desktop extension. Availability and organization policy can affect setup. See [Claude's official custom connector instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

## ChatGPT

Enable **Developer mode** under **Settings → Security and login**. In **ChatGPT Plugins**, choose the plus button, enter the MCP URL, choose OAuth for account access, and create the connection. Enable the plugin in a conversation. For basic public data, use an unauthenticated connection if the host offers one. Developer mode and extension availability depend on the account and workspace policy. See the [official OpenAI connection guide](https://developers.openai.com/plugins/deploy/connect-chatgpt).

Try: “Show Runecloth's last day in Normal Alliance, then compare Alliance and Horde.” A host supporting MCP Apps can display the interactive chart. The server also declares ChatGPT sidebar entry points for the market explorer, covering a general sidebar and a conversation sidebar. A host without these UI extensions can still use the JSON tools and answer in text. The [official OpenAI extension overview](https://developers.openai.com/plugins/build/extensions) describes those host surfaces.

The inline chart and explorer work anonymously: no token is needed for basic prices, listed quantity and seven-day hourly/daily history. With contributor or premium access, the same widget adds minute charts, longer daily windows, daily estimated listed/sold/expired volume, an order book aggregated by buyout price, and market analysis including fair value, estimated sell-through and days of supply. Volume bars represent full UTC-day totals, even on an hourly chart; missing observations are never filled in. Refresh checks account access again and removes deeper panels when sign-out or lost access is detected. Your ChatGPT plan does not grant an Auction House FYI tier.

In the ChatGPT desktop app's custom MCP form, choose **Streamable HTTP**, enter the URL and leave bearer-token/environment-header fields empty for OAuth. Save, restart the connection if prompted, then select **Authenticate** on the saved server. Sign in with the Auction House FYI account that holds your contributor or premium access. Ask the assistant to call `get_access` to verify the connection's current features. See [OpenAI's desktop MCP instructions](https://learn.chatgpt.com/docs/extend/mcp).

Adding this URL privately is separate from publishing a plugin for everyone. Public listing requires its own packaging, submission and review; this implementation does not imply marketplace approval.

## Tools and example questions

| Task | Tools | Example |
| --- | --- | --- |
| Check access and discover markets | `get_access`, `list_markets` | “What data can I access, and which markets have observations?” |
| Find an item and interpret it | `search_items`, `get_item` | “Find the Runecloth item key.” |
| Research prices and movement | `get_item_price`, `get_candles`, `compare_markets` | “Compare Runecloth in Normal Alliance and Horde over seven days.” |
| Inspect depth | `get_order_book` | “Show the price levels and stack sizes for Runecloth.” |
| Analyze and screen | `get_item_analysis`, `screen_market` | “Which items are below their recent fair value with low estimated days of supply?” |
| Show a graph or explorer | `render_item_chart`, `open_market_explorer` | “Chart Runecloth's last day, then open the explorer.” |
| Explore recipes and materials | `search_knowledge`, `render_knowledge`, `get_recipe`, `get_recipe_cost` | “Find a tailoring recipe and estimate its material cost in Normal Alliance.” |
| Research an item across sources | `get_item_research`, `get_item_locations` | “What is known about this item, and which location references are available?” |
| Explore quest references and client questlines | `search_quests`, `render_quests`, `get_quest`, `get_questline` | “Look up Rascally Rodents and label the reference's compatibility.” |
| Search map and area labels | `search_atlas` | “Find Elwynn Forest in the sourced map catalogue.” |
| Manage the watchlist | `get_watchlist`, `set_watchlist` | “Add Runecloth to my watchlist and preserve everything already there.” |
| Manage alerts | `list_alerts`, `create_alert`, `update_alert`, `delete_alert` | “Alert me when Runecloth falls to 2 silver per unit.” |
| Manage saved boards | `get_boards`, `set_boards` | “Show my saved boards.” |

Account changes require explicit confirmation. The assistant must first show the proposed change and obtain approval, then send `confirmed: true` with a write call. Replacing a watchlist or boards document and deleting an alert are annotated as destructive. Confirmation is a host/assistant interaction requirement; the boolean is not evidence that the user actually approved. Configure your host's write-tool approval controls too.

`set_watchlist` replaces the whole ordered list. Read the current list before adding or removing an item, then confirm the complete replacement. `update_alert` replaces the alert input and re-arms it; an edit is not a partial patch. Verify the result with the corresponding read tool. If contributor access expires, reconnecting does not restore the feature without renewed credit or premium access.

## Interpret answers correctly

Prices are integer **copper per unit**: 100 copper is one silver; 10,000 copper is one gold. HTTP times are Unix milliseconds. Keep the exact item key, including suffixes and pet species, and the exact market. The chart defaults to the last day; seven days is the next useful comparison window.

Always distinguish observation time from the response's server time, and hourly data from latest observed data. A null row means there is no observation; a null price means none listed at the last complete observation. Neither means an item is free. Listed quantity is public; deeper volume is an estimate from book changes, not confirmed sales. Cite the item page, for example `https://auctionhouse.fyi/item/14047?m=forever.normal.alliance.us`.

The MCP server never bids, buys, posts or cancels game auctions. It exposes market facts and the caller's website settings. Public responses contain no uploader identity, seller, bidder or character names. Watchlists, alert notes and boards are private to their owner, but the assistant host receives the tool results you request; review its own data handling settings separately.

## Deployment and administrator setup

The MCP endpoint runs in the existing Cloudflare Worker. Each deployment uses its own Clerk instance and credentials; dev or preview tokens must not authenticate in production. Deploy through the repository's CI pipeline when the change is merged. Do not publish a Worker manually as part of connector setup.

Clerk provides the OAuth authorization server; Auction House FYI publishes protected-resource discovery at `/.well-known/oauth-protected-resource/mcp` and verifies incoming OAuth access tokens through Clerk. No new Worker secret is needed: `CLERK_PUBLISHABLE_KEY` identifies the deployment's issuer, `CLERK_SECRET_KEY` supports backend verification, and `API_BASE` determines the canonical `/mcp` resource/audience (the request origin is used when unset).

In the appropriate Clerk Dashboard, open **OAuth applications → Settings → Client onboarding**. Enable **Publish CIMD support** for clients using Client ID Metadata Documents. Enable **Publish DCR support** only for clients requiring Dynamic Client Registration. CIMD clients require PKCE with `S256`. See [Clerk's official MCP server integration guide](https://clerk.com/docs/expressjs/guides/ai/mcp/build-mcp-server).

Create our custom scope keys under **OAuth applications → Scopes**: `market:read`, `watchlists:read`, `watchlists:write`, `alerts:read`, `alerts:write`, `boards:read` and `boards:write`. Assign the appropriate allowed scopes to each OAuth application/client and advertise them in authorization metadata. Advertising alone does not assign permission. For full account management, include all seven keys in **Default scopes for dynamic clients**. Some hosts omit `scope` during registration: Clerk then uses these defaults as the client's scope ceiling, so a market-only default prevents later consent from adding watchlist or alert permissions without an administrator updating that client. Dev and production use all seven defaults; users see the permissions on the initial OAuth consent screen, and each account change still needs explicit confirmation. Clients intended only for market reads can request or be assigned `market:read` alone. An OAuth scope allows an action category and never grants a paid feature. Missing permission asks the host for additional consent within the client's allowed scope ceiling; a tier refusal remains a feature error. See [Clerk custom scopes](https://clerk.com/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth#custom-scopes) and [CIMD client scope controls](https://clerk.com/docs/guides/configure/auth-strategies/oauth/client-id-metadata-documents).

Enable the Clerk instance's OAuth application setting `aud_claim_enabled: true` before connecting authenticated clients. Clerk's [Backend API contract](https://github.com/clerk/openapi-specs/blob/main/bapi/2021-02-05.yml) defines this setting on `PATCH /instance/oauth_application_settings`; it allows access-token audiences derived from the RFC 8707 `resource` parameter. Configure each deployment's Clerk instance separately.

Select **Opaque access tokens** under OAuth applications → Settings → Access tokens (`oauth_jwt_access_tokens: false`). Clerk can revoke opaque tokens immediately. Its JWT access tokens remain valid until expiration, even when verified through the Backend API, so backend verification alone does not make JWT connections immediately revocable. Auction House FYI supports both formats for compatibility; use opaque tokens for new connections.

The client must request the deployment's `/mcp` URL as its OAuth `resource`; this becomes the token audience when audience claims are enabled. Old tokens without that audience are refused. Clerk's [authorization and token OpenAPI contract](https://github.com/clerk/openapi-specs/blob/main/fapi/2021-02-05.yml) documents RFC 8707 resource binding. The Worker checks revocation and expiration with Clerk's access-token verification endpoint and obtains current billing access on every OAuth request, rather than retaining a premium role in a long-lived MCP token.

Never expose the Clerk backend secret to the chart iframe or assistant. If onboarding is disabled, public reads can work while OAuth sign-in fails. A pre-registered client ID may be needed for a host that cannot register dynamically; configure its permitted redirect URIs in Clerk rather than inventing a callback URL.

Before calling a deployment verified, run the repository checks and exercise discovery, tool listing, public prices, free-account history, paid depth, rate limiting and account isolation. Then use real host accounts to complete OAuth, render the chart/explorer, confirm a watchlist change, create/edit/delete a test alert and revoke the connection. Test an expired contributor as well as an active premium account. Check both supported UI hosts and a tools-only client. Record exactly which hosts and accounts were tested; local protocol tests do not prove real-host OAuth or UI compatibility.

No addon files or in-game behavior are changed by MCP support. No `/reload` or full client restart is needed for these connector steps. In-game behavior remains outside MCP verification.
