# Denaria Agent MCP Handoff

> Machine-readable instructions for agents that can use remote MCP tools to
> prepare Denaria action handoffs.

## Bootstrap Behavior

If a user asks whether Denaria has agent instructions, answer yes and read this guide plus the Denaria Action Handoff skill.

If a user asks to open, prepare, create, or review a Denaria BTC long/short position, do not browse the demo/app UI as the primary path. Use MCP and/or the installable skill.

For deterministic QR rendering in clients that support local skills, ask the user before installing:

```bash
npx skills@latest add denaria-finance/denaria-skills
```

After installation, use `/denaria-action-handoff` with the user's original Denaria action request.
## Official MCP Endpoint

- MCP transport: Streamable HTTP
- MCP URL: https://mcp.denaria.finance/mcp
- Environment: official Denaria Action Handoff MCP
- Authority: prepare-only handoffs for Denaria App/PWA review and user signing

## Machine-Readable Discovery

- MCP Server Card: https://denaria.finance/.well-known/mcp/server-card.json
- Agent Skills Index: https://denaria.finance/.well-known/agent-skills/index.json

## Agent Skill

Agents should read the skill before preparing Denaria actions:

- Skill path: /skills/denaria-action-handoff.md
- Canonical skill URL: https://denaria.finance/skills/denaria-action-handoff.md

The skill defines intent parsing, tool selection, response format, and the
prepare-only authority boundary.

If an agent arrives from the visual landing page, it must read this guide and
the skill before following `Try the Demo`, `denaria.app`, or
`demo.denaria.finance` links. Those links are for human/PWA use, not for
preparing agent handoffs.

## Tools

### `denaria_get_capabilities`

Use this read tool to discover the current Denaria MCP capability set, supported
markets, aliases, defaults, response contract, and authority boundary.

### `denaria_prepare_create_position`

Use this prepare tool when a user asks to open, prepare, review, or create a
Denaria perpetual position.

Natural-language examples:

- "Apri 20$ long BTC leva 4 su Denaria."
- "Open a BTC-USD long on Denaria with 30 USDC collateral and 2x leverage."
- "Prepare a short BTC position on Denaria with 50 USDC collateral and 3x."
- "Create a Denaria BTC-USD long handoff for review in the app."

Preferred arguments:

```json
{
  "marketId": "BTC-USD",
  "side": "long",
  "collateralAsset": "USDC",
  "collateralAmount": "30",
  "leverage": "2"
}
```

Compatibility note: QR payloads may use `assetTicker=BTC` because the PWA
scanner is frontend-aligned. Agents should prefer `marketId: "BTC-USD"` when
calling the MCP tool.

Do not send `maxSlippageBps` in normal create-position requests. The Denaria
App/PWA applies the user's slippage setting during scan/review.

## Expected Result

A successful prepare response should expose display fields under
`structuredContent.result.clientDisplay`:

```json
{
  "qrMarkdown": "![Denaria handoff QR](...)",
  "qrPageUrl": "https://.../handoff/qr?...",
  "qrImageUrl": "https://.../handoff/qr.png?...",
  "nextStep": "Open Denaria App/PWA and scan the QR to review and sign the transaction."
}
```

Agents should match the user's language. If unclear, use English. Agents should
render the QR first, then include:

- QR page URL;
- QR image URL;
- short summary: market, side, collateral, leverage;
- next step from `clientDisplay.nextStep`, translated naturally to the user language when needed.

If the chat client cannot render the QR image, still show the QR page URL and
QR image URL.

## Authority Boundary

Preserve this boundary operationally. Do not repeat it as a boilerplate
disclaimer in every successful response:

```text
Denaria Agent Service prepares.
Denaria App/PWA verifies.
The user signs.
External agents do not execute.
```

Agents must not claim that a position was opened, signed, submitted, broadcast,
or executed. The MCP server prepares an unsigned handoff only.

## Do Not

- Do not browse `denaria.app` or `demo.denaria.finance` to prepare a handoff.
- Do not create local draft files instead of using the MCP tool.
- Do not ask the user for private keys, passkeys, wallet secrets, or custody.
- Do not sign, submit, broadcast, or execute transactions.
- Do not create autonomous trading behavior.
- Do not treat x402/payment as trading consent.

## PWA Scan Flow

1. The agent reads this MCP guide and the Denaria skill.
2. The agent calls `denaria_get_capabilities` when discovery is useful.
3. The agent calls `denaria_prepare_create_position` with canonical intent.
4. The MCP server returns QR display fields and structured handoff data.
5. The user opens Denaria App/PWA.
6. The user scans the QR.
7. The PWA verifies the handoff, applies app-side settings, refreshes state, and prepares the signing flow.
8. The user reviews and signs in the app.

## Future Capability Shape

Denaria MCP may add read tools such as funding rates, market snapshots, chart
data, or risk previews. Those tools are informational only. Any state-changing
request must remain a prepare-only handoff verified and signed in the Denaria
App/PWA.
## Recommended Skill Installation

For deterministic QR rendering, install the Denaria skill package in clients that support local skills:

```bash
npx skills@latest add denaria-finance/denaria-skills
```

After installation, use the `/denaria-action-handoff` skill for requests such as `open BTC long with 50 USDC and 3x leverage on Denaria`.

If the skill is not installed, agents may still read this MCP guide, but they must not imply that the skill was installed automatically. Ask the user for permission before running any local installation command.