Integrating with an AI coding agent

Many teams integrate FingerTrackID with an AI coding agent. This page gives the agent the documentation in the format it reads best and the rules it must not break. The implementation handoff remains the brief for the integration itself.

Quick start

1. Download the integration file. In the console, Integração e saúde › Arquivo da integração downloads fingertrackid.integration.json. A company administrator or integration manager generates it. Save it at the root of the repository that integrates FingerTrackID (the integration file).

2. Store the secret yourself. Whoever received the HMAC secret once in the console puts it straight into the backend’s secret manager, read by the backend as FTID_HMAC_SECRET_HEX. It never goes to the agent (what never goes to an AI).

3. Add the MCP server to your agent. In Claude Code, from the repository root:

   claude mcp add --scope project fingertrackid -- npx -y @fingertrackid/mcp@0.1.3

   Other clients are in the MCP server. An agent without MCP reads /llms-full.txt and the integration file instead.

4. Give the agent the rules. Paste the rules block into AGENTS.md, CLAUDE.md or your tool’s equivalent.

5. Ask the agent to integrate. In Claude Code, run the server’s prompt with your tags, comma-separated:

   /mcp__fingertrackid__integrate_fingertrackid login,withdrawal

   In another agent, or without MCP, paste the integration prompt. The agent reads the integration file and adds one fail-open call per tag with the server SDK. It then wires the Web SDK token into your existing request and validates a synthetic request body.

6. Check the real credential yourself. Pipe the secret from your secret manager into npx --no fingertrackid-server check (how). It sends one real assessment in shadow mode and prints the verdict. Then review the agent’s work before real traffic.

The integration prompt

Copy this prompt into your AI coding agent, from the root of the repository that holds your site and backend. It works with or without the MCP server. The agent stops for your confirmation before it edits anything, and it never needs the secret.

Integration prompt

Paste it into your AI coding agent, or open it in one.

Integrate FingerTrackID into this project, in shadow mode: FingerTrackID recommends, and our
system keeps deciding and acting as it does today.

Sources, in this order:
- The fingertrackid MCP server, when it is connected: start with ftid_read_manifest.
- fingertrackid.integration.json at the repository root: the issued values (API origin,
  application public key, allowed origins, collection origin, key_id, Web SDK package). Never
  invent them or copy them from an example.
- The documentation, https://docs.fingertrackid.com/llms-full.txt. The published contracts win
  over any prose or example.

Never ask for, print, log, commit or store the HMAC secret. The backend reads it at runtime, by
name, as FTID_HMAC_SECRET_HEX from our secret manager. If a step needs its value, stop and tell me.

Show me your plan before you edit anything, then work in this order:

1. Inventory. Find where users sign in (including MFA and redirects such as Google sign-in), sign
   up, recover a password and take sensitive actions (withdrawals, transfers, changes of email,
   phone or password). Propose one lowercase tag per moment, such as login, signup,
   password_recovery or withdrawal, using the FingerTrackID templates. Wait for my confirmation.
2. Missing inputs. Check the integration file. If the collection origin, a server credential with
   assessment:write or the Web SDK package is missing, tell me what to do in the console, and
   continue only with the work that does not depend on it.
3. Backend. In Node.js, install the server SDK with the exact version:
   npm install --save-exact @fingertrackid/server@0.1.2
   Create one module with one function per tag (the MCP tool ftid_server_recipe generates it).
   In another language, implement the signature from
   https://docs.fingertrackid.com/api/authentication/ and match the public test vector first.
   - Call each function after our own checks and before our product acts: for login, after the
     real authentication and MFA. Keep our own decision.
   - Fail open: when FingerTrackID is slow, unavailable or misconfigured, the product works as
     today, and the failure is logged without secrets.
   - subject_ref and account_ref are keyed pseudonyms the backend derives, for example
     HMAC-SHA-256 of our internal ID with a key only the backend holds. Never an email, tax ID,
     phone number or name.
   - Log only identifiers and verdicts: tag, result kind, assessment_id, recommended action and
     correlation ID. Never the token, the signature or the request body.
   - When a result is UNAVAILABLE or UNEXPECTED_RESPONSE, keep result.operation with our record
     so it can be resent.
4. Browser. Install the private Web SDK archive named in the integration file's sdk_package. A
   person downloads it from the console. Verify its SHA-256 and SHA-512 against the file, then
   run npm install --save-exact --ignore-scripts ./fingertrackid-sdk-web.tgz. Never install a
   public package with a similar name. Then follow
   https://docs.fingertrackid.com/web-sdk/collection/#the-recipe:
   - one module with initializeSdk, only in browser code, with the publicKey and
     collectionOrigin from the integration file, and createActionContextHelper;
   - prefetch() on the first focus or pointer-down of each assessed form, never at page load,
     and only after any consent our privacy rules require;
   - take() once per submit;
   - the token and its expiresAt, or null, sent inside the existing authenticated,
     CSRF-protected request;
   - the helper closed on logout or account switch.
   The SDK never reads form values or passwords.
5. Site configuration. Add the collection origin to connect-src in our Content-Security-Policy.
   Keep that origin out of tracing header propagation (Sentry tracePropagationTargets, Datadog
   allowedTracingUrls, OpenTelemetry propagateTraceHeaderCorsUrls).
6. Checks.
   - Run npx --no fingertrackid-server self-check.
   - Validate one synthetic request body (ftid_validate_request in the MCP server).
   - Add tests for the fail-open paths: FingerTrackID unavailable, and a null token.
   - Run our test suite.
7. Hand-off.
   - List every file you changed, and what I must still do in the console.
   - Ask me to run npx --no fingertrackid-server check with the secret piped from our secret
     manager. It sends one real assessment in shadow mode.

Documentation for the agent

File	Content	Use it for
/llms.txt	A short summary of the platform, its rules and a link to every documentation set	The agent’s starting point
/llms-full.txt	Every page of this site in one plain-text file	Complete integration work
/llms-small.txt	The same pages with whitespace removed; every note, caution and expandable section is kept	Smaller context windows

The three files are generated from these pages at every publication, so they say nothing the pages do not. The published contracts (OpenAPI and JSON Schema, linked from the API overview) win over any prose or example, in these files and on every page.

The integration file

In the console, Integração e saúde › Arquivo da integração (also in Início, in the SDK step) downloads fingertrackid.integration.json. Save it at the root of the repository that integrates FingerTrackID: the agent reads the issued values from it instead of copying them by hand.

Field	Content
api_origin, documentation, request_profile	The production API origin, this documentation for agents and the request profile to send
secret	Only the name of the variable the backend reads the secret from, FTID_HMAC_SECRET_HEX. Never the secret
application	The application ID, slug, name, environment, browser public key and allowed origins
collection	The confirmed first-party collection origin, or null until the collection domain is active
server_credentials	Each current server credential’s key_id, capabilities and approved rate
sdk_package	The approved Web SDK archive’s version, SHA-256 and SHA-512, or null

The file holds public identifiers only, so it can be committed. Download it again when a key, the SDK package or the origins change: it does not update itself. Its contract is the integration manifest schema.

The MCP server

@fingertrackid/mcp is a local Model Context Protocol server for coding agents that support MCP. It runs on the developer’s machine over stdio, reads the integration file and public values, and changes nothing. No tool accepts the HMAC secret.

Add it with the exact version. In Claude Code, for this project:

claude mcp add --scope project fingertrackid -- npx -y @fingertrackid/mcp@0.1.3

Other clients that read an mcpServers file, such as .mcp.json:

{
  "mcpServers": {
    "fingertrackid": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fingertrackid/mcp@0.1.3"]
    }
  }
}

Start the agent from the repository root, where the integration file is. Then ask it to run the integrate_fingertrackid prompt, or to use the tools directly:

Tool	What it does
ftid_read_manifest	Reads the integration file and lists what is still missing in the console
ftid_list_templates	The ten common moments to assess, with the suggested tag and references (templates)
ftid_server_recipe	A complete TypeScript module for the server SDK, one fail-open function per tag
ftid_validate_request	Checks a request body exactly as the API reads it
ftid_explain_signature	The ten canonical lines and the MAC for a body, under the public test secret
ftid_check_vector_mac	Compares a signer in any language with the public test vector
ftid_interpret_response	Explains an assessment or a Problem, and whether to retry
ftid_check_collection_domain	Reads public DNS and TLS for your collection domain, only for a domain of the application’s origins in the integration file

The server also serves the public contracts as resources. Every tool is read-only; the first real call still runs from your backend, with the secret it reads from your secret manager.

Rules for your repository

Paste this block into the instructions file your agent reads (AGENTS.md, CLAUDE.md or your tool’s equivalent) in the repository that calls FingerTrackID.

Repository rules

Paste them into AGENTS.md, CLAUDE.md or your tool's equivalent.

## FingerTrackID integration

Documentation: https://docs.fingertrackid.com/llms-full.txt. The published contracts win over
any prose or example.

- Shadow mode. FingerTrackID recommends; this system decides and executes every action. Never
  block, allow, hold or settle anything because of a recommendation unless the product team
  decided it explicitly.
- Fail open. If FingerTrackID is slow, unavailable or misconfigured, the product keeps working
  with its own decision, and the failure is reported, not hidden.
- HMAC secret. Read it at runtime from the server-side secret manager, by name. Never ask for
  its value, and never print, log, commit or store it, or put it in a test, fixture, example or
  browser-exposed variable.
- Issued values. The key_id, the browser public key, the collection origin and the DNS records
  come from the FingerTrackID console. Never take them from a documentation example or from
  another application.
- Signing. FTID-HMAC-SHA256-V1 over the decoded secret bytes, never the hexadecimal text.
  Reproduce the published test vector byte for byte before the first real call.
- Body. Serialize it once. A retry resends the same bytes with a new X-FTID-Request-Id
  (UUIDv7), the current X-FTID-Timestamp and a new signature. Content-Type is exactly
  application/json, with no Content-Encoding.
- References. subject_ref and account_ref are keyed pseudonyms created by this backend (for
  example HMAC-SHA-256 of the internal ID with a backend key). Never send an email, tax ID,
  phone number, name or account number. account_ref requires subject_ref.
- Browser token. The event_context_token goes from the browser SDK to this backend inside the
  existing authenticated, CSRF-protected request. It is not a result; never log it.
- Response. trust_score null means no score, never 0 or 100, and INCONCLUSIVE is a normal
  outcome. Keep X-Correlation-Id for support.
- Logs. Never log the secret, the token, the signature or the full request body.

What never goes to an AI

• The HMAC secret. A company administrator or integration manager receives it once in the console and puts it straight into the backend’s secret manager. The agent writes code that reads it by name; it never needs the value.
• Real user data. Production logs, request bodies with real references, event context tokens and console exports stay out of prompts and agent context.
• Console access. Your password, authenticator codes and console session are personal.

An agent that asks for the secret

If an agent asks for the secret value to test a call, the answer is no. It checks its signing code with the public test vector and self-check, which use a synthetic secret that authenticates nothing. The first real call runs from your backend, with the secret it reads from your secret manager.

Checking the agent’s work

• The signature self-check prints the expected MAC on the Node.js that runs your backend.
• The integration guidance covers failing open, the time budget and testing in production without a sandbox.
• The integration checklist is the review list before real traffic.