For AI agents

The independent verifier coding agents like Codex, Claude Code, and Cursor call before shipping an API change: a deterministic verdict over the CLI, and agent-led Organization onboarding over Dino's hosted MCP server.

Coding agents like Codex, Claude Code, and Cursor change APIs faster than anyone can review by hand. An agent cannot trust its own grade: the check has to come from outside the generation loop. Dino is that check. The agent builds, Dino verifies the running API and returns a deterministic verdict, and the agent branches on it with no human in the middle.

How an agent calls Dino

An agent drives the CLI, which needs no account: run dino scan --format json against any endpoint, read the verdict on stdout and the branch signal from $?. To set up a Dino Organization and its APIs, an agent uses the hosted MCP server (see MCP).

dino scan --endpoint https://your-api.com/graphql --fail-on-high --format json --quiet

An agent reads three surfaces, in the order it acts on them:

  1. Exit code (branch): 0 clean · 2 usage · 3 policy gate failed · 4 transient · 5 config · 6 partial · 70 crash. Branch on $? with no parsing. See exit codes.
  2. JSON verdict (understand): --format json emits a DinoResult on stdout (verdict.health.verdict, findings, verdict.coverage); stdout stays pure, so it pipes to jq. See JSON output.
  3. Error envelope (recover): on exit 2/4/5/70, the last stderr line is {"error":{"kind","message","retryable","exitCode"}}. retryable says retry (transient) or stop (permanent). See error envelopes.

Is the change safe to ship?

dino scan --fail-on-high exits 3 when any HIGH or CRITICAL finding exists and 0 when clean, enough to decide continue-or-stop. Exit 6 (partial) is not a pass: read verdict.reasons to see what could not be verified.

Set up and resume

dino skill --install writes the agent skill (the setup, verify, read, fix, reverify loop) to .claude/skills/dino/SKILL.md, matched to the installed CLI version. dino schema prints every command, flag and exit code as clispec JSON, so an agent can check what the installed version accepts instead of guessing. When dino init is missing an input it exits 2 and puts a nextAction on the stderr envelope: { "type": "ask_user", "inputs": [...], "resume": { "type": "run_command", "bin": "dino", "args": [...] } }. Ask the human for each input (for a secret, ask them to set the named env var), then re-run resume.bin with resume.args, appending each collected input by its flag.

MCP: onboard an Organization from your agent

Dino's MCP server is a remote URL you connect over OAuth, not an npm package (there is no @dino-hq/mcp-server to install). Add it to your agent, for example in Claude Code:

claude mcp add --transport http dino https://api.usedino.dev/mcp
claude mcp login dino

claude mcp add only saves the server configuration; claude mcp login dino (or /mcp inside Claude Code, then authenticate dino) starts the OAuth sign-in below. Until then the server shows Needs authentication.

The agent leads; the human makes every identity and consent decision in the browser:

  1. Sign in. Connecting opens Dino sign-in. The human verifies their email with a one-time code, then chooses one of their Organizations or creates a new one. Dino never picks one for them; an existing user can create another Organization with the same email.
  2. Confirm name and residency (new Organization only). The human confirms the Organization's name and where its data is stored: United States or European Union. Residency cannot change later. The agent may suggest; the human decides.
  3. Approve access. The human approves the agent's access to that Organization, and the browser returns to the agent. If the agent client cannot resume, reconnect from the agent.
  4. Onboard the API. Once connected, the agent runs: bootstrap (admits the API, Environment and Target; no secrets) → create_auth_profile → open_credential_handoff only when its nextAction is credential_required (the human types the credential on Dino's page, never in chat) → get_auth_profile → propose_target_connection with the human's answers on where scans run and for which purposes → the human's approval (below) → get_target_connection.
  5. The human approves the Target Connection on Dino's approval page. Authorizing a Target Connection grants Dino authority over the human's system, so only a human signed in to Dino directly can decide it. get_human_action_request returns an approvalUrl: the agent gives the human that link, the human reviews exactly what the Connection allows (destination, scope, credentials and every limit) and authorizes or declines it there, and the agent polls get_presentation_request until it is decided. Dino refuses this decision from the agent, even when the agent acts for the human. A changed configuration needs a new approval.

Credential entry is not authorization: the one human approval is the Target Connection, bound to the exact configuration the human reviewed. For a Target whose API signs in with a login, the agent creates the identity with strategy login_flow and proposes the login steps with propose_authentication_flow (secrets only as {{name}} placeholders); the human then enters each named secret on the handoff page. Follow the nextAction in every result, read current state after a reconnect instead of assuming it, and treat a pending, refused, or expired result as not done. New Organizations start on the free plan; get_commercial_state shows the plan and entitlements. To work in a different Organization, clear the stored authorization first, because the client keeps and refreshes its OAuth tokens and reconnecting reuses the current Organization: in Claude Code, run claude mcp logout dino (or choose Clear authentication for dino in /mcp), then claude mcp login dino and choose the other Organization.

Protected Discovery: withheld responses

When Discovery reads a protected OpenAPI document or GraphQL schema as a credentialed identity, Dino never keeps the credential. Before anything from the response is stored, Dino checks it for protected credential material:

  • the credential and each of its secret components, at any length (a Basic password, a login-flow secret, a token or session the flow acquired);
  • the literal text, its escaped and decoded forms, and the response headers Dino records.

Usernames and other identifiers are only checked as part of the whole credential.

On a match, the response is withheld. Nothing of it is kept, the Operation stops LIFECYCLE_FAILED with CREDENTIAL_REFLECTED, the detail reads "The response matched protected credential material and was withheld.", and the earlier usable Discovery stays current.

The check is conservative. Dino cannot tell a coincidence from a reflection, so a short or common credential value (for example 1234, admin, or a word that also names a schema type) withholds any response that happens to contain it. A withheld response is not a confirmed leak, an invalid credential, or a statement about credential health.

The failure's nextAction is provide_input (discovery_response_withheld). Check that the source is the intended endpoint. If the match is a coincidence, upload the document or SDL instead, or ask the human to use a more distinctive credential. There is no minimum credential length. Credential entry is not authorization: the one human approval is the Target Connection, bound to the exact configuration the human reviewed. For a Target whose API signs in with a login, the agent creates the identity with strategy login_flow and proposes the login steps with propose_authentication_flow (secrets only as {{name}} placeholders); the human then enters each named secret on the handoff page. Follow the nextAction in every result, read current state after a reconnect instead of assuming it, and treat a pending, refused, or expired result as not done. To admit Initial Discovery for a Target you know only by its id (for example from list_auth_profiles), read its apiId and environmentId from list_target_connections; you do not need the original bootstrap response. New Organizations start on the free plan; get_commercial_state shows the plan and entitlements. To work in a different Organization, clear the stored authorization first, because the client keeps and refreshes its OAuth tokens and reconnecting reuses the current Organization: in Claude Code, run claude mcp logout dino (or choose Clear authentication for dino in /mcp), then claude mcp login dino and choose the other Organization.

Human tasks on Dino's task page

Some work belongs to the human: a secret, an approval, stopping access, a Dino service key. The agent starts it or asks for it, hands the human a link to Dino's task page, and reads the outcome itself. The human does it signed in to Dino directly. A consequential decision needs a sign-in from the last 15 minutes, so the page may ask the human to sign in again first.

  • Connect an OAuth2 API on one page. start_connect_journey takes the Target, either a name for a new identity or an existing authProfileId, and the human's answers on where scans run and for which purposes. Give the human the pending step's taskUrl. On that page they configure the OAuth2 client (unless you sent a typed draft), enter the client secret, and approve the exact Connection. Poll get_presentation_request with the Request id. The journey ends connect_proposed and links the approval Request in checkpoint.createdArtifactReferences. An identity that already has its configuration and secret goes straight to the approval.
  • Ask a human to stop access. You never stop access yourself. request_operator_action names one action and your why: credential.revoke with a credentialReferenceId, or connection.suspend, connection.revoke or connection.retire with targetId, connectionId and version. The human sees what the action affects and confirms once on the page. A human can also stop access with no agent and no link, at https://api.usedino.dev/task?action=stop-access.
  • Dino service keys are issued by humans. Issuing, regenerating and revoking a Dino service key happens only on https://api.usedino.dev/task?action=service-keys. list_service_keys gives you ids, each key's Service Account role, whether it is active, and that taskUrl, never key material. A key authenticates as its own Service Account, not as the human who issued it. Dino shows a key once; if it was not stored, ask the human to regenerate it.
  • Read why a Request ended. Every Request carries status and statusReasonCode. For example, FAILED with operator_action_already_in_effect means another action had already stopped that access, so the human's confirmation changed nothing.

Discover an API and manage its sources

Discovery turns an API's OpenAPI document or GraphQL schema into Dino's canonical inventory. Over MCP the agent finds the exact estate, sends the source, reads what Dino discovered, and manages the source's lifecycle. Every result names its next step.

  • Find the exact estate from a name. find_apis with the API's name returns every API whose name matches exactly, ignoring ASCII letter case only (other letters must match as written), never a similar one; ambiguous (with matchCount) means several match, so ask your human which. get_api_estate lists every Environment with its Target count and a page of 20 Targets (pass nextCursor as cursor). Each Target carries its destination, the Connection Dino would use for anonymous Discovery contact (or discoveryConnectionReason, why there is none it could use), its newest Operation, its current generation, and a nextAction: estate_discovery_in_progress, estate_discovery_available, estate_discovery_failed or estate_discovery_source_required. Several Environments or Targets may share a name: tell them apart by id. This is how a fresh agent recovers after losing context.
  • Send a file Dino should read exactly as it is. For an OpenAPI document or GraphQL SDL you should not copy into the conversation, call open_source_intake with the apiId, its format (json or yaml for REST, sdl for GraphQL) and, if you know them, its expectedDigest, expectedByteLength and provenance (where it came from: server, repository, registry_export, client_bundle or unknown, plus revision, variant and whether it was bundled; recorded as stated, never as proof). Give your human transfer.taskUrl: they choose the file on Dino's page, signed in. Or their own tool sends the raw bytes with their own credential as an authenticated PUT to transfer.path with its Content-Length. The file never passes through MCP, and there is no upload credential to pass on. Follow it with get_source_intake; once it is REGISTERED, admit it with admit_initial_discovery and source: {kind: "intake", intakeId}. An intake waits one hour. A file that is too large (over 1 MiB), malformed, cut short, not the expected digest, or different from what the intake already registered registers nothing and says why. External $ref links are never fetched; they stay visible gaps.
  • Read the canonical inventory. get_discovery_generation with include: "inventory" returns { generationId, inventoryPage }, at most 32 KiB as a whole, small enough to read inline (pass maxBytes, up to 262,144, for larger pages; admittedBytes states the budget, and a cursor keeps it). Read the generation itself without include. The inventory comes as one stream: its header (section header) first, then every entry with its section and index, plus each section's count and nextCursor (pass it as cursor). An item too large for one page arrives as consecutive fragments of its JSON text: join their text and parse it. The items of every page, in order, rebuild the stored inventory; HTTP serves the same pages. A missing or altered artifact is DISCOVERY_ARTIFACT_CORRUPT, never an empty page.
  • Revoke a wrong or old source. Tell your human, then call revoke_discovery_source with the sourceVersionId and your reason. It is never used again, every generation built on it leaves the current Discovery at once, and history stays readable. A repeat changes nothing. Revoking does not delete the stored document.
  • Erase a stored source only with your human's approval. request_discovery_source_erasure names the sourceVersionId, its current digest (read it with get_discovery_source) and why. Nothing is erased yet. Give your human the pending step's approvalUrl: only they decide, signed in to Dino directly, and Dino refuses the decision from you. Tell them exactly what is erased: the stored document and the inventory of every generation built on it. Their confirmation completes it, so poll get_presentation_request. From then on the content is never served (DISCOVERY_CONTENT_ERASED), and get_discovery_source shows ERASURE_PENDING until every stored object is deleted, then ERASED. A minimal record (digest, size, origin, admission and the audit) stays. A changed or already erased source is refused; a declined request erases nothing.