Connecting an AI client

Tallyray runs an MCP server, so an AI assistant that supports remote MCP servers can read your reports, click log, catalog and rules, and ask for changes. It can ask, but never change anything by itself: every change waits until you confirm it in the portal. The AI tools page lists each tool, its scope and which ones wait for you.

Connect a client

In your AI client, add a remote MCP server with this address: https://api.tallyray.com/mcp.
The client finds how to sign in from the server’s metadata and sends your browser to the portal.
Sign in, if you are not. The grant is for the workspace your session is in: use the account switcher to change it.
The consent page shows the client’s name (in its own words), the host of its address and of its redirect address (with a warning when that is your own computer’s address, which any program there can claim), the workspace, and the access it asks:
- Read: your reports, logs, catalog, rules and connections.
- Read and ask for changes: also lets it ask for changes you confirm. A viewer is offered Read alone.
Allow or Deny. The page says what no client ever does, and that the grant ends in 90 days.

Clients are known by an OAuth client metadata document at an https address. There is no dynamic registration and no client registered ahead, so the client must support this way of identifying itself.

What a grant is

One per person, workspace and client. Granting again changes its scopes.
The client gets an access token that lasts 15 minutes and a refresh token that turns at each use. A refresh token used twice ends the grant.
A grant ends after 30 days unused, or 90 days after it was made; the client then sends you to consent again.
A person can have 10 clients in a workspace, and a workspace 50.

Revoke

Under Settings, AI clients, you can revoke your own grants, and the workspace’s owner any grant. It takes effect at once, everywhere. A grant also ends when its person is removed from the workspace or leaves it, when the workspace ends, when a refresh token is used twice, or when the client revokes it.

The same page lists each grant’s calls (each recorded before it is made) and the changes it asked for.

Changes wait for you

Reading goes straight through. A change does not. These ask for a change and wait: running a rule for real, pausing or resuming a source’s objects, a path or a campaign, undoing a rule’s action, and making, changing, archiving and restoring campaigns, offers and landers (up to 50 of one kind at once).

When a client asks, the tool answers with a page address. Open it in the portal: it shows exactly what the change would do, with the fields it sets, with hosts new to the workspace marked. Confirm it and Tallyray makes it at once with your own permissions, or decline it. Meanwhile:

Only the grant’s person confirms, and only a buyer (a viewer cannot).
A request waits up to 24 hours. One whose targets changed since is stale and can only be dismissed.
Settings shows a badge with the number waiting.
The client learns the outcome by asking again, or with get_confirmation.
A grant can have 10 changes waiting at once and can ask for 50 in a day.

Running a rule dry is the one change that happens at once, because it changes nothing: it records what the rule would do.

Why this is safe to try

Everything in a result is data your buyers and visitors wrote (names, URLs, placements, notes). The server tells the client to treat it as data, never as instructions, so a visitor’s words cannot press a button in your session.
A stolen grant can read and ask, nothing more.
The server never sends anyone somewhere others are not sent: it has no tool that cloaks.
Requests from a web page (those carrying an Origin header) are refused.
Cross-device links are never in a tool’s answer.

API keys, for your own scripts

For a script of your own, the workspace’s owner makes an API key under Settings, API keys. A key has one or more scopes:

Scope	Allows
`buyer:read`	read your catalog, connections, deliveries, calls and conversions
`buyer:write`	change them as a buyer would
`stats:read`	read reports

The key (pk_…) is shown once. A key never manages members, secrets, domains, credentials or other keys, and a key cannot grant an AI client. Send it as Authorization: Bearer pk_… to https://api.tallyray.com/v1/buyer/…. Revoking it stops it at once. See the API reference.