Six stable MCP contracts · v0.3.0 RC

Tentaclaw tool reference.

The public tool surface is intentionally small. Discovery, one-time questions, conversation creation, and conversation continuation remain distinct operations.

Overview Skills Tools Security Errors

Summary

Tool	MCP approval class	Persistent Poppy state	Required inputs
`tentaclaw_version`	Read-only	No	None
`poppy_get_boards`	Read-only discovery	No	None
`poppy_get_chats`	Read-only discovery	No	`board_id`
`poppy_ask`	Write-capable remote operation	No conversation thread; may consume credits	`board_id`, `chat_id`, `prompt`
`poppy_create_conversation`	Write-capable	Creates thread	`board_id`, `chat_id`
`poppy_chat`	Write-capable remote operation	History only when requested; may consume credits	`conversation_id`, `board_id`, `chat_id`, `prompt`

`tentaclaw_version`

Returns the running Tentaclaw version without contacting Poppy. Use it first to confirm that the expected runtime is connected.

`poppy_get_boards`

Retrieves boards available to the configured Poppy credential. Call only when the approved board identity is unknown. A configured allowlist should constrain what the agent can use; do not enumerate for curiosity.

`poppy_get_chats`

Retrieves chat assistants for one approved board. Required input: board_id. The server rejects a board excluded by configured policy.

`poppy_ask`

Asks one bounded question without requiring a persistent conversation. Required: board, chat, and prompt. Optional fields include model, additional context, plaintext, and a streaming compatibility flag. In this candidate, requesting streaming fails closed with streaming_not_supported; no partial stream is silently treated as complete. When model is omitted, Tentaclaw defers to Poppy's supported default rather than hard-coding a provider model.

Send only necessary context. Never include credentials, unrelated private material, or operational instructions copied from untrusted content.

`poppy_create_conversation`

Creates a Poppy conversation for an approved board/chat pair. Optional name may label it. This is state-changing and should be used only when continuity is needed.

`poppy_chat`

Continues a known approved conversation. Required: conversation, board, chat, and prompt. Optional fields include model, context, plaintext, a streaming compatibility flag, user, source, and save_history. Candidate default for history saving is false. Requesting streaming currently returns streaming_not_supported until a live-tested adapter exists.

Response and error contract

Candidate tools return a structured success/error envelope. Expected safe errors include missing or unreadable credential, disallowed destination, request too large, response too large, timeout/network failure, upstream HTTP error, malformed response, and invalid configuration. Errors must not contain the API key, full credential-bearing URL, prompt body, or response body.

No silent fallback: on access denial, malformed output, or ambiguous destination, report the safe error. Do not select another board, create another conversation, or retry beyond server policy.

Not exposed by Tentaclaw

Arbitrary visual-node construction or connection
Programmatic chatbot publication
A chatbot URL as an API execution contract
Customer identity, billing, credit reservation, throttling, central revocation, reseller tenancy, or multi-account routing
Generic HTTP requests or shell execution