Your agent has taste.

Why agents and samples fit.

Most commerce APIs are built around a payment step, and payment is where agents get stuck: someone has to approve a charge. On Handsel there is no charge. Every listing is free, so checkout is only two questions: is this person eligible, and did they consent?

Consent is encoded in the key your human gives you. It says which categories you may claim from, how many claims you get per 30 days, what data a brand may see, and when the key expires. Inside those bounds your agent can act on its own. Humans use the same catalog through the website, and both get the same rules.

Live in three steps.

1. Create a member account

   Your human signs up as a member and adds a shipping address and taste preferences on /me. Physical samples need an address.

2. Mint an agent key

   On /me, open Agent keys and choose New key. Pick a monthly cap, the allowed categories, what data to share, and an expiry. The hsk_… secret is shown once, so copy it somewhere safe.

3. Add the MCP server

   Point your MCP client at https://handsel.co/mcp with the key as a Bearer token.

Connect your client

claude mcp add --transport http handsel https://handsel.co/mcp \
  --header "Authorization: Bearer hsk_..."

{
  "mcpServers": {
    "handsel": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://handsel.co/mcp",
        "--header", "Authorization: Bearer hsk_..."
      ]
    }
  }
}

{
  "mcpServers": {
    "handsel": {
      "type": "http",
      "url": "https://handsel.co/mcp",
      "headers": { "Authorization": "Bearer hsk_..." }
    }
  }
}

# List the tools
curl -s https://handsel.co/mcp \
  -H "content-type: application/json" \
  -H "Authorization: Bearer hsk_..." \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Search for samples (works without a key)
curl -s https://handsel.co/mcp \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"search_samples","arguments":{"category":"drink","limit":3}}}'

Five tools, one endpoint.

The server speaks MCP over Streamable HTTP: JSON-RPC 2.0 requests sent with POST /mcp, answered with plain JSON responses. Supported methods are initialize, notifications/initialized, tools/list, tools/call and ping.

Auth: send Authorization: Bearer hsk_…. search_samples and get_sample work without a key. Every other tool acts for a member, so it needs one. Tool results come back as JSON in a text content block.

{
  "samples": [{
    "id": "smp_k3v9",
    "title": "Cold-brew concentrate",
    "category": "drink",
    "kind": "physical",
    "value_cents": 1400,
    "remaining": 212,
    "demo": false,
    "brand": { "name": "Northbound" }
  }]
}

{
  "sample": {
    "id": "smp_k3v9",
    "description": "Two 8oz bottles…",
    "regions": ["US"],
    "subscribe_price_cents": 2400,
    "subscribe_interval": "month",
    "status": "live"
  }
}

{
  "claim": {
    "id": "clm_7d2q",
    "status": "claimed",
    "code": null
  }
}
// digital samples may return a redeem "code"

{
  "claims": [{
    "id": "clm_7d2q",
    "status": "shipped",
    "via": "agent",
    "sample": { "title": "Cold-brew…" },
    "feedback": null
  }]
}

{
  "feedback": {
    "claim_id": "clm_7d2q",
    "rating": 3,
    "would_buy": false,
    "comment": "Too sweet for us."
  }
}

Raw JSON-RPC

{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": { "name": "claim_sample", "arguments": { "id": "smp_k3v9" } }
}

Prefer plain HTTP?

Everything the MCP server does is also available as JSON over HTTP. Errors look like {"error": "message"} with a 4xx status. Authenticate with the same Bearer key, or with the browser session cookie.

Try it

This sends a real request from your browser to this server.

// The response will appear here

DemoShowcase listings come back with "demo": true. They're here to show how Handsel works while real brands onboard, so claiming one returns 409. Skip them when choosing for your human.

Permission, scoped.

An agent key is a standing permission slip from a member. It is the only way an agent can act for someone, and every limit on it is checked on every claim.

Claim rules

These apply to every claim, from a person or an agent:

• One per sample per person. A second claim on the same sample returns 409.
• Six claims per member per 30 days across all keys and the website. Keys can be set lower.
• Physical samples need an address on the member's profile, otherwise 422.
• The sample must be live, with stock remaining, and not a demo listing.

Found by machines.

Agents that land on Handsel without instructions can discover everything from two well-known files.

When the answer is no.

Errors are JSON with a readable message. Over MCP, the same message comes back as a tool error (isError: true), so your agent can explain it to the human.

Shop like you mean it.

Brands pay to put real product in real hands. Keep the network worth joining.

Full rules are in the Agent Use Policy.