Connect your AI client with MCP

Use an AI client to explore your company’s retained campaigns, affiliate participations, revenue trends, referrals, attributed sales, commissions, and payout records. LiftVector’s Model Context Protocol (MCP) connection is read-only: it cannot change records, synchronize payments, or send money.

Before you connect

You need a LiftVector merchant account with access to the company you want to read, a trusted AI client, and a browser where you can sign in to LiftVector. Affiliate-only access is not sufficient. See the quickstart if you have not created your company.

Use a current Claude Code or Codex CLI installation with remote HTTP MCP and browser OAuth support. Your client’s own account or subscription requirements are separate from LiftVector. The endpoint is:

https://app.liftvector.app/mcp

Use this application address, not your merchant portal address. You do not need a LiftVector API key, provider secret, or a token pasted into a configuration file.

Connect Claude Code

Run this in the project where you want to use LiftVector:

claude mcp add --transport http liftvector https://app.liftvector.app/mcp
claude mcp login liftvector

The login command opens the browser for native OAuth authorization. Follow Approve one company below. The default server configuration is local to this project; run Claude Code from the same project when using it.

After approval, inspect the connection from that project’s terminal:

claude mcp get liftvector
claude

Inside the interactive Claude Code session, /mcp shows the server’s status and also provides an authentication option. For reauthorization from the terminal, run claude mcp login liftvector again. Removing a local server configuration is not a substitute for revoking its LiftVector connection.

Connect Codex CLI

Add the server, then start its native browser login:

codex mcp add liftvector --url https://app.liftvector.app/mcp
codex mcp login liftvector

The add command may already start OAuth when it discovers that authorization is needed. If it completes successfully, you do not need to repeat login immediately. Otherwise use the explicit login command above. Follow Approve one company in the browser, then return to the terminal for the login result.

Inspect the saved server configuration and open Codex:

codex mcp get liftvector
codex

Inside Codex, /mcp shows configured tools and server information. Saved configuration alone does not prove authorized reads work; use the verification prompt below. To reauthorize later, run codex mcp login liftvector again.

Approve one company

1. Sign in on LiftVector’s browser login page using your usual password, passkey, or two-factor flow. If you are already signed in, check that it is the intended account.
2. Review the requesting client’s name and callback address. The client name is self-reported, not a verified identity. Approve only a flow you initiated in a client you trust; deny an unexpected request.
3. Choose one company and approve financial read access. The connection is bound to that account, client, and company with the merchant:read permission. Declining grants no access.
4. Let the browser return to the client’s callback, then return to the client.

A different company needs its own consent. If you keep multiple companies connected in one client, use distinct server names and verify each with merchant_context; switching companies in your browser workspace does not retarget an existing connection.

Verify the connection

Ask your client:

Use LiftVector's merchant_context tool. Show the company name,
website, merchantId, and permission before reading financial records.

The result should identify exactly the company you approved and show merchant:read. If the company is wrong, stop and revoke that connection before authorizing the intended company. A successful context read confirms authorized access to that company, not that financial evidence is complete or current.

Useful questions to ask

These prompts use shipped tools. Ask the client to use returned LiftVector IDs, not guessed IDs or customer emails. Detail reads need the exact campaign and affiliate IDs from the relevant record. An affiliate filter also requires its campaign ID.

Compare campaigns and revenue

Use campaigns_list and affiliates_list to map this company's
campaigns and participations, paging through all retained history.
For each campaign, use campaign_get and campaign_terms_list, then
compare dashboard_get results without combining currencies.
Use revenue_trend_get in adjacent 90-day windows for older history.
Report incomplete evidence instead of treating empty or zero totals
as proof of no activity.

Directories include disabled campaign and affiliate history. campaign_get returns the terms effective now; campaign_terms_list pages current, prior, and scheduled versions without internal author identities. Affiliate reads expose LiftVector IDs and real display names when available; email-backed provisional names are returned as null, never as contact details. Link tokens, promotion IDs, and name/email search are also excluded.

dashboard_get returns lifetime metrics for the company or one returned campaign ID. Its asOf is query time, while evidence.latestSaleCheckAt is only the maximum retained sale check. Check hasUncheckedSales, discoverySatisfied, updatesPending, hasUnresolvedFailures, and complete before interpreting stored zero totals. revenue_trend_get uses an inclusive startsOn, exclusive endsOn, and a named time zone; each window is 1–90 days but may cover any historical dates. Gross and net revenue follow payment dates and current authoritative refunds. Commission follows signed ledger-entry dates. Results stay separated by currency.

Explore referrals and attributed sales

Use referrals_list and sales_list for this company. Show retained
referrals and attributed sales, paging as needed. Keep currencies
separate and report evidence coverage and observation times.
Do not treat missing or unknown values as zero.

A referral is an anonymous retained attribution relationship, not a visitor, click, lead, or person profile. It may have no retained sales. Unattributed sales are excluded; older attributed sales may have no referral ID. Use referral_get for a referral’s linked sales, sale_get for sale details, and sale_refunds_list or sale_disputes_list for their separate histories.

Understand a commission

Pick an attributed sale from sales_list and inspect it with sale_get
and commission_get using its campaignId, affiliateId, and saleId.
Explain its retained applied terms, original automatic earning,
and signed corrections. Flag missing terms or incomplete evidence.
Do not recalculate the commission or assume today's campaign terms.

commission_get uses the sale’s retained terms, not the current campaign offer. Its history contains automatic entries and corrections; participation-level manual adjustments are in statement_get, not this sale history. Missing terms and unknown amounts remain unknown.

Review balances and statements

Use balances_list to show each campaign/affiliate participation's
currency balances, evidence completeness, and payout blockers.
Distinguish pending, reserved, paid, available, recoverable, and
payable amounts. For a returned participation and currency, use
statement_get to explain its ledger entries without netting across
currencies or participations.

balance_get reads one exact participation. Balances are committed ledger totals; available money can be negative, and payable money is gated by structured blockers. Statement totals cover the lifetime of that participation and currency, independently of the page. These reads do not reserve money, prepare a payout, or promise payment.

Inspect retained payout bookkeeping

Use payouts_list, then payout_get for a returned payout ID.
Explain the original payout snapshot, retained allocations,
included sales, and later corrections. Distinguish the snapshot
from current balance/readiness and report unresolved evidence.
Do not interpret a payout record as proof of a bank transfer.

Payouts describe external-payment bookkeeping, not money moved by LiftVector. Prepared, paid, cancelled, and reversed records remain readable. A retained allocation describes that payout’s history; an entry’s current allocation may be different. An unknown legacy correction baseline is unresolved, not proof that there were no corrections.

Read results safely

• Stored data, not live provider queries. Reads never contact a payment provider, refresh evidence, enqueue synchronization, reconcile a sale, or write financial records. Observation times and lastCheckedAt describe stored evidence. A balance’s asOf is not its provider-evidence freshness time.
• Unknown is not zero. Amounts are integer minor units in each record’s currency. Keep currencies and participations separate. null, incomplete, unsupported, or unresolved evidence must not become an all-clear result. Empty pages and zero stored totals do not establish complete financial history or zero provider-side liabilities.
• Pages are bounded. List/history reads default to 50 items; limit is 1–200 and offset starts at zero. Ask the client to continue through each collection’s totalCount, advancing by returned items. payout_get independently pages allocations, included sales, and corrections. Counts describe retained records, not provider completeness.
• Paging is not a frozen snapshot. Imports or corrections may shift offsets while you read. Deduplicate by LiftVector IDs and restart traversal if you need a consistent view across updates. There is no bulk-export tool.
• Access stays company-scoped. The approved company comes from the connection, not a merchant ID supplied by the AI. Disabled or unclaimed affiliate participations can remain readable; this does not grant affiliate impersonation.

Tools expose structured financial facts, timestamps, and LiftVector IDs. They do not expose customer identities, contact emails, account/member IDs, provider identifiers or keys, credentials, internal actors, free-text notes, raw payloads, or payment instructions. There are no name/email search tools. Your trusted AI client still receives the returned business data: review that client’s privacy and retention settings before approving access. Read-only does not mean non-sensitive.

Staying connected

The client handles credentials through OAuth; do not copy tokens yourself. Access tokens last 15 minutes. Compatible clients automatically refresh them using rotating refresh credentials while the connection remains authorized. The refresh lifetime ends 30 days after initial authorization; rotation does not extend it. At that point, or when the client requests authorization again, repeat its browser login flow.

Restarting a client can reconnect using its saved authorization. Normal browser logout does not revoke MCP access. Each connection remains bound to its original account, client, company, and permission. Account-security changes, lockout, merchant-role loss, or loss of membership in that exact company block subsequent reads and refreshes. Signing back in alone does not repair invalidated authorization; after resolving access problems, authorize again when prompted.

Inspect or revoke a connection

Open your workspace, then Account settings → Connections. Review each connected app’s company, authorization time, and last use. Names are self-reported. Times use your browser’s local time; “Not yet used” means no successful authenticated request or refresh has been recorded. Expired connections can remain listed until revoked.

Choose Revoke and confirm to immediately block that connection’s access and refresh credentials. Cancel leaves it unchanged. Revocation affects that connection, not every connection on your account, and does not erase data the AI client already received. You can still revoke your own connections after losing company membership or the merchant role.

To connect again after revocation, repeat the client’s native browser authorization. To disconnect permanently, revoke in LiftVector first, then remove the server from the client if desired.

Troubleshooting

The browser does not open, or consent/callback fails

Use the authorization link shown by your client only for a login you just initiated, and keep that client running until the callback finishes. Do not share the link. For a client running over SSH or in a container, the browser must be able to reach that client’s callback; follow the client’s remote-environment instructions rather than editing the callback URL.

Start a fresh authentication attempt if the request expired, was already used, or you denied consent. Check the browser account and company selection. If no eligible company appears, confirm your merchant role and membership with the company administrator. Do not substitute a merchant portal URL for the application endpoint.

Authorization expired, was revoked, or reads stopped working

Use Claude Code’s /mcp authentication option or codex mcp login liftvector to authorize again. If access still fails, check Account settings → Connections, account lockout/security changes, and your current merchant role and company membership. Reauthorization cannot restore a role or membership you no longer have. Resolve that access issue first; do not work around it with another person’s credentials.

Check the endpoint without credentials

These commands send no tokens and keep TLS verification enabled:

curl -i https://app.liftvector.app/mcp
curl --fail --show-error https://app.liftvector.app/.well-known/oauth-protected-resource/mcp

An unauthenticated MCP request is expected to receive HTTP 401 with a Bearer resource_metadata challenge. The discovery document should identify the application /mcp resource and its authorization server. A browser login cookie is not MCP authorization, so opening /mcp in a signed-in browser is not a connection test.

DNS, TLS, gateway errors, or a missing discovery document are endpoint/network problems, not proof of bad company consent. Check the URL, network/proxy settings, and trusted certificates; never disable TLS verification or paste an access token into a URL. These diagnostics are expectations, not a claim that a particular production deployment has been verified.

For help, contact [email protected] with the client/version, time, and redacted error. Never send passwords, tokens, authorization headers, consent/callback URLs, or unredacted financial output.

Client command references

See the current Claude Code MCP documentation and Codex MCP documentation. Client commands and UI can change; use the installed client’s help if your version differs.