Preference MCP Docs

Preference supports registered agent keys and linked account access. Quotas refresh daily. All Polymarket and Kalshi tools are free and do not consume credits.

Store keys in an environment variable, local credentials file, or secret manager. Never paste real keys into shell history, prompts, logs, shared config, issues, PRs, or docs.

Keep issuance flows distinct. API-first agent registration returns a pref_agent_* key and examples use PREFERENCE_API_KEY. Signed-in portal and onboarding flows create account API keys for human-owned clients; connector snippets use PREFERENCE_MCP_KEY for those secrets.

Verify keys inside MCP with preference_account_status. Do not use /v1/auth/whoami to verify pref_agent_* keys.

# API-first agent key shown by POST /v1/agents/register.
PREFERENCE_API_KEY=pref_agent_xxx

# Signed-in account API key shown once after create/rotate in portal onboarding.
PREFERENCE_MCP_KEY=<account_api_key>

# Placeholders only. Put the real key in your secret manager,
# MCP client env settings, or a private local file outside shared repos.

Any MCP client that supports remote HTTP / Streamable HTTP servers should send the Preference endpoint with a standard Bearer Authorization header. stdio-only clients need a bridge or a client/runtime that supports remote MCP. Include the explicit Streamable HTTP transport when your client supports it; some clients otherwise fall back to legacy HTTP+SSE.

mcp_servers:
  pref:
    url: "https://pref.trade/mcp"
    transport: "streamable-http"
    headers:
      Authorization: "Bearer ${PREFERENCE_API_KEY}"

If you are using an account-backed key from the portal, point the header at PREFERENCE_MCP_KEY instead.

If your client starts with GET /mcp and receives 400 Missing MCP-Session-Id, it is using legacy SSE semantics. Configure remote MCP with Streamable HTTP so the session starts with POST /mcp initialize.

For Claude Code with an API-first agent key:

claude mcp add --transport http pref \
  "https://pref.trade/mcp" \
  --header "Authorization: Bearer ${PREFERENCE_API_KEY}"

For Codex with an API-first agent key:

export PREFERENCE_API_KEY='pref_agent_xxx'
codex mcp add pref --url https://pref.trade/mcp --bearer-token-env-var PREFERENCE_API_KEY

For Codex with a signed-in account API key from the portal:

export PREFERENCE_MCP_KEY='<account_api_key>'
codex mcp add preference --url https://pref.trade/mcp --bearer-token-env-var PREFERENCE_MCP_KEY

For manual Claude Desktop-style setup, add the MCP URL in the client UI and use /guide when you want the visual setup flow.

Start with the protocol-level tools/list check, then call preference_account_status through tools/call. The status tool is free and does not consume daily tool quota.

curl -s -X POST "https://pref.trade/mcp" \
  -H "Authorization: Bearer ${PREFERENCE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"tools","method":"tools/list","params":{}}'

curl -s -X POST "https://pref.trade/mcp" \
  -H "Authorization: Bearer ${PREFERENCE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"status","method":"tools/call","params":{"name":"preference_account_status","arguments":{}}}'

A successful status response should show an identity that is not anonymous, a tier or quota object, remaining calls, and a reset time.

Then search current capabilities before calling a domain-specific tool. This keeps your integration resilient as the MCP surface evolves.

curl -s -X POST "https://pref.trade/mcp" \
  -H "Authorization: Bearer ${PREFERENCE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"capability-search","method":"tools/call","params":{"name":"search_tools","arguments":{"query":"prediction markets"}}}'

Preference exposes structured world data through MCP tools. Use search_tools to discover the current tool surface instead of assuming a fixed list. Search by intent, inspect returned tool names, descriptions, and input schemas, then call the matching tool with tools/call.

• Prediction markets and market-moving context
• Flight tracking and movement signals
• Global news and media monitoring
• Economic indicators and macro data

• Anonymous identity: the MCP client is missing the Authorization header or using a stale anonymous config.
• MCP client header mismatch: use Authorization: Bearer ... in MCP client configs. X-API-Key is not the agent onboarding contract and should not be used for MCP client setup. If switching the same key to Bearer works, do not regenerate it; create or rotate a key only when the saved secret was lost, revoked, or still fails with the Bearer header.
• Existing anonymous config: remove the old MCP server entry and add it again with auth.
• Timeout or unreachable upstream: retry and verify you are using the generated endpoint for your environment.
• Lost key: keys are shown once. Create or rotate a key if the secret was not saved.

Treat Preference keys as secrets. Keep them out of shared configs and logs, use the least privilege available for account-backed keys, and validate outputs before relying on them for financial, legal, safety, operational, or other high-impact decisions.