# Nettipoika agent quick start (HTTP API v1)

- Environment: `dev`
- Release: `dev-3a382c5`
- Source commit: `3a382c557c1643ae17b0ea70ef7836d47c0a8bb4`
- Canonical installation discovery: `https://sivusto-dev.nettipoika.fi/llms.txt`
- Product discovery index: `https://nettipoika.fi/llms.txt`

## Connect safely

1. Read `GET https://sivusto-dev.nettipoika.fi/api/v1/capabilities` and `GET https://sivusto-dev.nettipoika.fi/openapi.json`.
2. Use the customer dashboard's copyable agent instructions for the intended site. Those instructions identify the exact hostname and `site_id` without containing a bearer token.
3. Generate independent random poll and continuation verifiers locally. Send only their SHA-256 challenges when creating the access request described by `https://sivusto-dev.nettipoika.fi/payment/openapi.json`.
4. Show the human only the returned approval URL. Wait for approval of the exact site and scopes, then poll at the response's instructed interval.
5. Connect an OAuth-capable MCP client to `https://sivusto-dev.nettipoika.fi/mcp`. Discover authorization through `https://sivusto-dev.nettipoika.fi/.well-known/oauth-protected-resource/mcp`.
6. Let the OAuth client renew the maximum-15-minute access token using its protected rotating refresh credential. If renewal fails or the connection is revoked, stop and request fresh human authorization.

Never ask the human to paste credentials into chat. Keep bearer tokens, refresh credentials, private keys and verifiers in protected client storage and send access tokens only in the `Authorization` header.

## Operate one authorized site

The HTTP API is canonical; MCP exposes the same bounded capabilities. Use the returned site hostname instead of constructing one from the product origin. Reads require the documented scope. Every mutation requires an `Idempotency-Key`, and revision-aware file changes also require the current base revision and ETags.

Long-running work returns `202 Accepted` and a pollable operation. A candidate is not ready until its health check and public HTTPS verification succeed. Code rollback selects a retained compatible release and does not roll database contents back. Human approval remains mandatory for payment, sensitive scope grants, recovery and destructive database actions.

Raw MCP clients initialize with protocol `2025-11-25` and send `MCP-Protocol-Version: 2025-11-25` on later requests. Prefer a conforming OAuth-capable MCP client over implementing token handling manually.