clipboard

Stash a string; pull from another agent or machine.

When to use

Call clipboard_put when an agent needs to hand a small text value to another agent, another machine, or the user — without writing to disk. Typical uses: OAuth tokens, config snippets, one-time secrets, short outputs one agent produces and another consumes.

Example user prompts

• Stash this OAuth token so the other agent can pull it once.
• Put the generated one-time code in pail clipboard for 15 minutes.
• Pass this short config value to my next session without writing it to disk.

MCP tool signature

clipboard_put(
    text: str,
    project: str | None = None,
    ttl_minutes: int = 60,
    max_pulls: int = 1,
) -> ClipHandle   # {handle_id, pull_url, expires_at}

clipboard_pull(handle_id: str) -> str

Example call

# Agent A: stash the token
clip = clipboard_put(text=oauth_token, ttl_minutes=30, max_pulls=1)
print(f'Pull URL: {clip["pull_url"]}')

# Agent B (different machine): retrieve it
token = clipboard_pull(clip['handle_id'])
# The clipboard is now consumed (max_pulls=1)

Return value

Returns a ClipHandle with handle_id, pull_url (web URL for human retrieval), and expires_at. clipboard_pull returns the raw text string directly.

Credit cost

0.5 actions per create call (rounds to 1 in daily accounting).

Notes

Clipboard entries are consumed on pull when max_pulls=1 (the default). There is no rendering — clipboard is for raw text only. For files or structured data, use share instead.

Recipes

See all recipes for copy-paste patterns that use clipboard and other tools together.