IPForge integration guide

Supported use cases

• Measure an organization's own links and persistent landing pages.
• Run transparent delivery or compatibility tests with owned or authorized inboxes, chats, recipients, and destinations.
• Review activity, source classification, and coarse device/session evidence inside the owning workspace.

A controlled test is diagnostic: a preview, image request, or browser event records what a delivery path did. It is not evidence that a named recipient read content, was at a precise place, or intended an action.

What the measurements mean

Human

A human classification means a capture contained browser signals and no currently recognized preview-bot, crawler, headless-browser, or hosting-network signal. It is a classification result, not proof of a person's identity, location, intent, or consent. Classifier coverage can change as services and signals change.

Unknown

unknown means the available signals were insufficient to make the classification. Unknown activity is excluded from human-oriented counts and must not be described as a human visit.

Deduplication

A repeat capture is marked duplicate when it has the same resource and fingerprint hash as an earlier capture within 24 hours. Human-oriented counters include only the first non-duplicate human capture in that window. This reduces repeat noise; it does not prove a unique person, since browsers, devices, networks, and fingerprints can change or be shared.

Device confidence

Device confidence is a coarse evidence read based on available browser/device signals, such as browser and OS family, device type, and whether signals agree or change over time. Use the phrase “same likely browser/device profile,” never “this is definitely the same person.” A fingerprint is technical evidence, not an identity credential.

Active dwell

Active dwell is opt-in, visible-tab time accumulated on a persistent IPForge landing page. Time pauses while the page is hidden; a short-lived session accepts small visible-time updates only. It does not measure reading, attention, or any activity after a redirect to a third-party destination. A redirect therefore means only that IPForge initiated the navigation, not that the destination loaded or was read.

Privacy and acceptable use

Use IPForge only in a workspace you own or are authorized to operate, for a stated purpose and with appropriate notice or consent. Owners should collect the minimum information needed for that purpose and honor applicable retention and deletion duties.

Do not use IPForge for covert person tracking, identity resolution, stalking, deceptive tracking links, or unauthorized surveillance. Do not collect credentials, keystrokes, form values, copied text, precise pointer paths, DOM/page contents, or other data outside the documented measurement scope. Do not expose customer links, capture records, IP addresses, raw fingerprints, tokens, or implementation secrets to a public endpoint or to a tool you do not operate.

An agent you operate may hold an API token you issued for your own workspace; that is the authorized way for software to act on it. Issue the token with the narrowest scopes the job needs, keep captures:raw off unless the job is the dashboard's own view, and revoke it when the job is done.

API and MCP

IPForge has an owner-authorized public API and a remote MCP server. Every call is authenticated with an API token a human issues once in the dashboard; no API operation or MCP tool issues a token or creates an account, and this guide does not describe account creation. Three calls take an agent from nothing to a measured link:

1. Issue a token. In the dashboard, Settings → API tokens → New token. The ipf_… secret is shown once; the default scopes are everything except captures:raw. Send it as Authorization: Bearer ipf_… on every request.
2. Create a link. POST /api/v1/links with a JSON body; the response is 201 with the link and its resolved public url — share that, never compose one. Creating a link costs at least one credit.
3. Read what happened. GET /api/v1/links/{id}/captures returns one row per deduplicated human/unknown visitor — class, coarse device, OS and browser family, country, first and last seen, visit count. Page with cursor, poll with since.

curl -X POST https://ipforge.xyz/api/v1/links \
  -H "Authorization: Bearer ipf_…" -H "Content-Type: application/json" \
  -d '{"title":"Launch","type":"redirect","redirectUrl":"https://example.com/launch"}'

curl https://ipforge.xyz/api/v1/links/{id}/captures \
  -H "Authorization: Bearer ipf_…"

The contract is /openapi.json (OpenAPI 3.1, generated from the server's own validators): 20 operations over activity, links, SVGs, captures, custom domains, credits and orders — a tracking SVG image is created, listed, read and measured exactly as a link is, under the same scopes, and GET /api/v1/activity answers "what real activity happened?" across every asset in one call; one error envelope { "error": { "code", "message", "field"?, "request_id" } } with a closed code set; X-RateLimit-* headers on every response. A link is served on one of the three platform domains — ipforge.xyz (the default), brokolli.xyz or tarology.xyz, any user's pick per link in the domain field — or on a custom domain the owner has verified. Credits are bought with USDC on Solana, Polygon or BNB Chain: create an order, send the amount from any wallet, verify with the transaction hash.

The same operations are MCP tools at POST https://ipforge.xyz/mcp (Streamable HTTP, the same bearer token). From Claude Code or another CLI/IDE host:

claude mcp add --transport http ipforge https://ipforge.xyz/mcp \
  --header "Authorization: Bearer ipf_…"

From claude.ai or ChatGPT: add a custom connector at https://ipforge.xyz/mcp and sign in. The sign-in is OAuth 2.1 and ends in a token that appears in the same Settings list, revocable like any other. Read tools return summaries (start with get_activity_overview); publish_draft is the only tool that spends a credit and requires confirm: true; no MCP tool returns raw visitor records under any token.

A token returns summarized, deduplicated, human-only evidence by default. captures:raw is an explicit per-token opt-in the owner grants to read what the dashboard shows, on GET /api/v1/links/{id}/captures?view=raw and its /api/v1/svgs/{id}/captures twin only. The complete machine-readable guide — every operation with its scopes, every error code, rate limits, bundles and chains, the MCP tools, the sign-in path — is /llms-full.txt.