# Palate setup for agents

You are an AI agent. A human gave you this guide so you can query Palate on their behalf. Palate lets users query context uploaded by Palate users: published work, claims, recommendations, archives, and other source material that is not easy to query anywhere else on the internet.

A query can target one Palate for one user's context, multiple Palates by handle, or the global Palate database. Use the scope that best matches the human's intent.

Operating rules:

- Ground every Palate answer in the returned answer, chunks, and citations.
- Keep Palate-grounded claims tied to Palate evidence.
- Treat API keys, wallet secrets, and payment credentials as secrets. Store them in a secret store or environment variable.
- A successful paid query is charged. Retry only when you know the previous call failed before completion.
- If a Palate call fails, say the Palate query failed and explain the next safe action.

## 1. Choose transport

Use MCP if your runtime supports remote MCP servers with headers. Use HTTP everywhere else. Both expose the same query surface.

### MCP

Global server:

```json
{
  "mcpServers": {
    "palate": {
      "url": "https://staging.palate.inc/mcp",
      "headers": {
        "palate-api-key": "${PALATE_API_KEY}"
      }
    }
  }
}
```

One-Palate server:

```json
{
  "mcpServers": {
    "palate-patrick": {
      "url": "https://staging.palate.inc/patrick/mcp",
      "headers": {
        "palate-api-key": "${PALATE_API_KEY}"
      }
    }
  }
}
```

Tools:

- `palate_query(question, scope?, paymentMode?, mode?, rail?, walletAddress?, channelIds?)`
- `palate_quote(rail?)`
- `palate_list_channels()`

If your MCP client cannot send the `palate-api-key` header, use HTTP with an API key or use the on-chain payment flow.

### HTTP

Base URL:

```text
https://staging.palate.inc
```

Recommended endpoint:

```text
POST /api/ask/query
```

Use this for global search, `@handle` search, `@creator/collection` search, explicit handle scopes, or a one-Palate scope.

Optional one-Palate endpoint:

```text
POST /api/palates/{slug}/query
```

Use this only when you already know the Palate slug and want every query pinned to that one Palate.

## 2. Choose payment

Prefer an API key when the human gives you one.

### API key path

Send the key on every request:

```http
palate-api-key: palate_your_key_here
```

Include `paymentMode` in every paid query:

- `"credits"` spends credits.
- `"unlocks"` spends unlocks.

No wallet, quote, or payment challenge is needed. API-key calls can use the key owner's authorized private scopes, saved favorites, and collection mentions when applicable.

### On-chain path

Use this only when no API key is available and you have a wallet/payment client.

Set `rail` in the first query:

- `"tempo"` for MPP/Tempo USDC.
- `"x402_base"` for x402 over Base USDC.

Palate returns HTTP `402` with a rail-specific challenge:

- Tempo/MPP: `WWW-Authenticate`
- x402: `PAYMENT-REQUIRED`

Pay with your rail client, then retry the same query with the protocol credential:

- x402 usually sends `X-PAYMENT`.
- MPP may send `Payment` or `Authorization: Payment ...`.
- MCP sends the credential in `_meta["org.paymentauth/credential"]`.

Successful on-chain responses include a receipt in the body and in the rail receipt header.

## 3. Ask a good Palate question

Use specific questions that name the expert, topic, timeframe, artifact, or decision the human cares about.

Good:

```text
What should I understand from @patrick about founder-led culture after CEO transitions?
```

Better when comparing experts:

```text
Compare what @patrick and @april say about pricing early-stage products. Include points of agreement and disagreement.
```

Avoid vague prompts like `Tell me about AI` unless the human truly wants global discovery.

## 4. Query with HTTP

### API key, synthesized answer

```bash
curl -s https://staging.palate.inc/api/ask/query \
  -H "content-type: application/json" \
  -H "palate-api-key: palate_your_key_here" \
  -d '{
    "question": "What should I understand from @handle?",
    "paymentMode": "credits"
  }'
```

Default `mode` is `"synthesized"`. The response is ready to present, but you must include citations.

### API key, raw chunks

Use raw mode when you need to write in your own voice, merge with other user context, rank evidence yourself, or inspect the source material before answering.

```bash
curl -s https://staging.palate.inc/api/ask/query \
  -H "content-type: application/json" \
  -H "palate-api-key: palate_your_key_here" \
  -d '{
    "question": "What do @alice and @bob say about pricing?",
    "scope": { "kind": "handles", "handles": ["alice", "bob"] },
    "mode": "raw",
    "paymentMode": "credits"
  }'
```

### One Palate by slug

```bash
curl -s https://staging.palate.inc/api/ask/query \
  -H "content-type: application/json" \
  -H "palate-api-key: palate_your_key_here" \
  -d '{
    "question": "What is this expert's view on distribution?",
    "scope": { "kind": "palate", "slug": "patrick" },
    "paymentMode": "credits"
  }'
```

Equivalent pinned endpoint:

```bash
curl -s https://staging.palate.inc/api/palates/patrick/query \
  -H "content-type: application/json" \
  -H "palate-api-key: palate_your_key_here" \
  -d '{
    "question": "What is this expert's view on distribution?",
    "paymentMode": "credits"
  }'
```

### On-chain query

```bash
curl -i https://staging.palate.inc/api/ask/query \
  -H "content-type: application/json" \
  -d '{
    "question": "What should I understand from @handle?",
    "scope": { "kind": "handles", "handles": ["handle"] },
    "rail": "x402_base",
    "walletAddress": "0x..."
  }'
```

If the request is answerable, this first call returns `402`. Pay the challenge and retry the same request with the payment credential header.

## 5. Query with MCP

List tools:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
```

Call `palate_query` through `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "palate_query",
    "arguments": {
      "question": "What should I understand from @handle?",
      "paymentMode": "credits"
    }
  }
}
```

Direct method calls also work:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "palate_query",
  "params": {
    "question": "What should I understand from @handle?",
    "mode": "raw",
    "paymentMode": "credits"
  }
}
```

For on-chain MCP, a payment-required response is JSON-RPC error code `-32042` with `error.data.challenges`. Pay with your rail client and retry with:

```json
{
  "_meta": {
    "org.paymentauth/credential": "payment-credential-from-client"
  }
}
```

Successful MCP tool results include `structuredContent`. On-chain receipts may appear in `_meta["org.paymentauth/receipt"]`.

## 6. Scopes and discovery

Scopes for `/api/ask/query`:

- Omit `scope` or use `{ "kind": "global" }` for global public search. `@handle` mentions in the question narrow global search automatically.
- Use `{ "kind": "handles", "handles": ["alice", "bob"] }` for one or more users. Maximum 20 handles.
- Use `@creator/collection` in the question to query a public collection.
- Use `{ "kind": "palate", "slug": "patrick" }` for one Palate.

Discovery endpoints:

```bash
curl -s "https://staging.palate.inc/api/palates?limit=25"
```

Returns public directory Palates with `slug`, `name`, `description`, `channels`, and endpoint paths. Use `nextCursor` for pagination. Show the human a short relevant set instead of a full directory dump.

Channel discovery for one Palate:

```bash
curl -s https://staging.palate.inc/api/palates/patrick/channels \
  -H "palate-api-key: palate_your_key_here"
```

After listing channels, pass `channelIds` to query only selected channels:

```json
{
  "question": "What does this expert say in podcast episodes about pricing?",
  "scope": { "kind": "palate", "slug": "patrick" },
  "channelIds": ["channel_id_here"],
  "paymentMode": "credits"
}
```

`channelIds` only works with one-Palate scope or the pinned one-Palate endpoint.

## 7. Response handling

Synthesized response:

```json
{
  "answer": "...",
  "citations": [
    {
      "label": "Source 1",
      "text": "...",
      "palateUrl": "/patrick/i/itemId?chunks=chunkId",
      "itemId": "itemId",
      "chunkId": "chunkId"
    }
  ],
  "scope": { "kind": "handles", "handles": ["patrick"] },
  "queryId": "query_id",
  "charge": "credits"
}
```

Raw response:

```json
{
  "mode": "raw",
  "chunks": [
    {
      "text": "...",
      "score": 0.91,
      "palateUrl": "/patrick/i/itemId?chunks=chunkId",
      "sourceUrl": "https://source.example/...",
      "publishedAt": 1735689600000
    }
  ],
  "queryId": "query_id",
  "charge": "credits"
}
```

Citing rules:

- Always include `palateUrl` citations in the final answer. Prefix relative paths with `https://staging.palate.inc`.
- `sourceUrl` can be omitted for private or non-public source material. Cite `sourceUrl` only when it is returned.
- If using raw chunks, synthesize only from the returned chunks and cite the relevant `palateUrl` values.
- Mention uncertainty when the returned evidence is partial or conflicting.

## 8. Errors

Common HTTP errors:

- `400 invalid_request`, `missing_question`, or `missing_payment_mode`: fix the request and retry once.
- `401 invalid_api_key`: ask the human for a valid Palate API key.
- `402 insufficient_balance`: ask the human to add credits/unlocks or switch payment method.
- `402` with payment challenge: pay with the selected rail and retry with the credential.
- `404 mention_not_found` or `not_found`: check handles, collection mentions, or slugs.
- `422 no_relevant_content`: Palate found no relevant indexed material. Say that plainly.
- `429 rate_limited`: wait until `resetAt` if provided.
- `503 retrieval_unavailable`: retry later or ask the human whether to proceed without Palate.

## 9. Maximize Palate usefulness

- Start with the human's named experts or handles. If none are named, use global search once, then narrow follow-up questions to the best matching experts.
- Prefer `synthesized` for direct Q&A and reports that can use Palate's answer as written.
- Prefer `raw` for long-form writing, multi-source comparison, agent workflows that need their own format, or answers that combine Palate evidence with user-provided context.
- Ask comparison questions when the user is deciding between views: "where do these experts agree, disagree, and what would each recommend?"
- For recurring interest in an expert, suggest following that Palate for free email updates; reserve paid API calls for specific questions.
- Keep the final answer useful: lead with the answer, cite the evidence, and separate Palate-grounded claims from your own reasoning.

Full judgment contract: https://staging.palate.inc/SKILL.md
Machine-readable spec: https://staging.palate.inc/openapi.json