PREF MCP Onboarding#

Goal:

1. create or reuse an agent-owned pref_agent_* key
2. save it safely
3. install https://pref.trade/mcp
4. verify the MCP is using that key, not anonymous quota

Once installed, the MCP is self-documenting — call any tool to discover its schema. Start with search_capabilities to explore 670+ data sources, then use browse_capabilities to find what you need.

Default Endpoint#

text

https://pref.trade/mcp

Do not use /mcp-gateway for normal client setup.

Do not open https://pref.trade/sign-up for agent onboarding. Browser sign-up uses human verification and is only for humans. Agents should use POST https://pref.trade/v1/agents/register.

Fast Onboarding#

1. Register if no key exists#

bash

curl -s -X POST "https://pref.trade/v1/agents/register" \
  -H "Content-Type: application/json" \
  -d '{"name":"Research Agent","description":"Agent using PREF MCP"}' | jq

The response includes:

• api_key: Your pref_agent_* key (shown once — save it now)
• claim_url: Share this with a human to link the agent to a Preference account and double the daily quota from 250 to 500 calls. Optional but recommended.

Key Storage#

⚠️ Save the key to a file immediately — do not echo it into terminal history, logs, or prompts.

bash

mkdir -p ~/.config/preference
echo '{"api_key":"pref_agent_xxx"}' > ~/.config/preference/credentials.json
chmod 600 ~/.config/preference/credentials.json

Or use an environment variable:

bash

export PREFERENCE_API_KEY='pref_agent_xxx'

Reference the key from your MCP client config (see below) — never inline the real key in YAML/JSON that gets shared.

2. Verify the key via MCP#

Important: /v1/auth/whoami does not accept pref_agent_* keys. Verify your key by calling preference_account_status inside MCP instead:

bash

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

Do not proceed until this returns your agent identity (not "anonymous").

3. Install the MCP#

Use a remote HTTP / Streamable HTTP MCP server config equivalent to:

yaml

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

For Claude Code:

bash

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

claude mcp list

For Codex:

bash

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

4. Verify inside MCP#

Call preference_account_status first.

Expected result:

• identity is the registered agent, not anonymous
• quota tier reflects agent-key access
• remaining calls and reset time are visible

preference_account_status is free and does not consume daily tool quota.

Troubleshooting#

"identity": "anonymous" in preference_account_status

This means your MCP client is running without the Authorization header. Common causes:

1. Stale anonymous config — you may have pref already configured without headers:

bash

claude mcp list              # check existing configs
claude mcp remove pref       # remove the anonymous one

Then re-add with auth (see Step 3 above).

1. Key stored but not picked up — verify the env var or credentials file:

bash

echo $PREFERENCE_API_KEY     # should show your pref_agent_xxx key

1. Header name mismatch — the header must be exactly Authorization: Bearer, not X-API-Key.

Security Rules#

• ⚠️ Save the key to a file immediately after registration, then reference the file path in configs. Never echo the key into terminal history, logs, chat, or prompts.
• Treat pref_agent_* keys as secrets.
• Never paste real keys into public logs, issues, PRs, docs, or prompts.
• Never edit .env files for the user.
• If identity is anonymous, the MCP client is not sending the Authorization header.