privy_set_custom_metadata
Set (overwrite) the `custom_metadata` map on the authenticated Privy user. Hits `POST /v1/users/{user_id}/custom_metadata`. The map values must be `string | number | boolean` — Privy rejects anything else at the API. Pass `userId` to target a different user (and the call will 403 if it does not match the caller's). Returns the updated `User` object so the agent can confirm the write without a follow-up read. Use this for the agent's per-user state (preferences, conversation memory, in-flight task state) without needing a separate Prisma table. For a shallow-merge write, use `privy_update_custom_metadata` instead.
Set (overwrite) the custom_metadata map on the authenticated Privy user. Hits POST /v1/users/{user_id}/custom_metadata.
Endpoint
POST /v1/users/{user_id}/custom_metadata
Input
The tool takes a single JSON object. Every field, its type, and an example are on the generated reference at GET /mcp/tools, under this tool's name.
Calling it
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": { "name": "privy_set_custom_metadata", "arguments": {} }
}Put your arguments in place of the empty object. A call that fails comes back as a normal result carrying isError: true and a message naming what went wrong, not as a JSON-RPC protocol error.
Notes
The map values must be string | number | boolean — Privy rejects anything else at the API. Pass userId to target a different user (and the call will 403 if it does not match the caller's). Returns the updated User object so the agent can confirm the write without a follow-up read. Use this for the agent's per-user state (preferences, conversation memory, in-flight task state) without needing a separate Prisma table. For a shallow-merge write, use privy_update_custom_metadata instead.
The full request and response shape, and a live playground, live on the generated reference at GET /mcp/tools.
privy_get_current_user
Get the authenticated Privy user, including their linked accounts (email, phone, OAuth, wallet, passkey, smart wallet), MFA methods, and `custom_metadata`. The tool defaults to the caller's DID — pass `userId` only when the agent already has a known id (and the call will 403 if it does not match the caller's). Returns the full `PrivyUser` object. Use this as the entry point for any user-level view: who am I, what data does Putty have on me, what wallets do I have linked. The `custom_metadata` map is the per-user state the agent reads and writes (see `privy_set_custom_metadata` and `privy_update_custom_metadata`).
privy_update_custom_metadata
Merge (shallow) the given `custom_metadata` keys into the authenticated Privy user's existing map. Hits `PATCH /v1/users/{user_id}/custom_metadata` (Privy's PATCH is a shallow merge, not a deep merge). Keys you pass are added or replaced; keys you do not pass are untouched. Pass `userId` to target a different user (and the call will 403 if it does not match the caller's). Returns the updated `User` object. Use this for incremental updates to the agent's per-user state — e.g. `privy_update_custom_metadata({ customMetadata: { lastSeenAt: Date.now() } })` on every chat turn. To overwrite the whole map, use `privy_set_custom_metadata` instead.