Why we built a gateway instead of putting an API key in an AI skill.

The pattern we reviewed

The artifact offered a convenient way for an AI agent to call a third-party workspace API. Its instructions asked the user to provide a credential-bearing value through the agent conversation, extract the reusable account credential, retain it in agent-accessible workspace state, and later build direct command-line requests with it.

The instructions also told the agent not to reveal the credential. That sounds reassuring, but it does not establish an enforceable boundary. Once a model, its tools, its workspace, or its shell can read the secret, every prompt, imported document, tool invocation, debug path, transcript, and extension in that environment becomes part of the exposure surface.

The violated invariant

We wanted one falsifiable rule: the AI agent and its skills must be able to request approved Poppy operations without ever receiving the account-wide Poppy API key.

That rule cannot be achieved through wording alone. A prompt can influence behavior; it cannot revoke authority the process already has. We needed a component outside the agent-visible instruction layer to own the credential and expose only narrow capabilities.

The boundary we chose

Tentaclaw is the MCP server. It reads the credential from a restricted local file outside the agent conversation, applies destination and request controls, makes the HTTPS request, and returns a controlled response. The agent sees MCP tool schemas; it does not see the key.

This is capability reduction. The agent does not receive arbitrary API authority and a warning to behave. It receives six named operations with bounded inputs and a server that can reject unsafe configuration or destinations.

The skills still matter

Removing the key from the skill does not make skills optional. It gives them the right job.

• tentaclaw-setup teaches safe installation, verification, rotation, incident handling, and migration without asking for the key in chat.
• poppy-operator controls when Poppy context is actually needed, resolves one approved board and chat, distinguishes read from write operations, and fails closed on ambiguity.
• poppy-board-research keeps research bounded, separates Poppy-provided claims from analysis, and rejects broad harvesting.
• poppy-content-workflow supports brainstorm, create, and rewrite flows while requiring human review and forbidding automatic publication.

Skills provide operating discipline. Tentaclaw provides the credential and execution boundary. Neither layer replaces the other.

Controls that follow from the design

• Local stdio transport for the release candidate, so no inbound port is required.
• HTTPS-only, allowlisted Poppy destination.
• Restricted key file with POSIX permission and symlink checks.
• Optional board and chat allowlists.
• Bounded request and response size, timeout, retries, redirect denial, and malformed-response handling.
• Metadata-only audit events; no prompt or response persistence by default.
• Skills that reject destination guessing, secrets in context, untrusted embedded instructions, and automatic external publishing.

What this does not solve

A gateway narrows authority; it is not magic. A user or process that can read the local key file or inspect the Tentaclaw process can still compromise the credential. Retrieved board content can still contain prompt injection. The upstream API still receives prompts and applies its own retention, usage, and account policies. A malicious or overprivileged MCP client can misuse every tool it is allowed to call.

That is why the release design also needs host hardening, least-privilege board/chat policy, explicit write semantics, context minimization, incident rotation, transparent data handling, live verification, and human review of consequential output.

Why we are not naming the reviewed product

Responsible security communication should improve the ecosystem without turning an architectural discussion into a public ambush. The evidence came from one artifact, not an exhaustive assessment of a vendor or service. Naming it would invite readers to generalize beyond what we actually proved.

The pattern is the point: any agent integration that moves a high-value reusable credential through chat, model-visible state, command arguments, or broad tool access should be redesigned so a separate trusted component owns the secret.

The release claim we are willing to make

Tentaclaw v0.3.0 is a release candidate, not a completed public release. The current build includes four first-party skills, a stronger local security boundary, configuration guides for four MCP clients, 24 automated tests across supported Python versions, a clean production dependency audit, reproducible packages, a software bill of materials, and verified checksums. Live Poppy testing, real-client validation, final review, and public release are still in progress.

When those gates pass, the claim will remain narrow: Tentaclaw gives supported MCP clients a controlled route to six documented Poppy operations without putting the raw Poppy key in the agent or skill.