# AI agents and MCP (https://talivia.com/docs/ai-agents)



Talivia exposes an account-level [Model Context Protocol](https://modelcontextprotocol.io/) endpoint at:

```text
https://talivia.com/mcp
```

Connect it once to let an approved AI agent work across the websites your Talivia account can access. The agent can read the same period-based analytics available in Talivia–including events, goals, funnels, acquisition, revenue, payments, journeys, and data quality–and can also install and verify tracking or open secure payment-provider setup.

## Choose your client [#choose-your-client]




Codex

Connect from the CLI with remote MCP and OAuth.




ChatGPT

Create a custom app in Apps & Connectors.




Claude

Add Talivia as a custom web connector.




Other MCP clients

Use Streamable HTTP and OAuth discovery.

## How authorization works [#how-authorization-works]

1. Add `https://talivia.com/mcp` to your MCP client.
2. The first protected request returns an OAuth challenge with Talivia's authorization metadata.
3. Your client opens Talivia in the browser. Sign in if necessary.
4. Review the requested scopes and approve the connection.
5. The client stores a scoped access token that remains active until you revoke the connection.

The agent never receives your Talivia password. Payment provider secrets also stay in Talivia: when Stripe or another provider needs authorization, the MCP tool returns a secure browser handoff instead of asking the agent to handle credentials.

You can review or revoke approved connections at any time in **Settings → AI agents**. Revocation immediately disables the stored token.

## Local npm bridge [#local-npm-bridge]

If your client expects a local stdio MCP server, use the published Talivia package:

```bash
npx -y @talivia/agent setup --agent codex
npx -y @talivia/agent checkin --agent codex
codex mcp add talivia -- npx -y @talivia/agent mcp
```

The setup command opens Talivia for browser approval. Check-in stores the approved, revocable local credential in `~/.talivia/config.json`, and the final command lets Codex start the authenticated stdio bridge.

## Codex [#codex]

Add the hosted endpoint:

```bash
codex mcp add talivia --url https://talivia.com/mcp
```

Then start browser authorization:

```bash
codex mcp login talivia
```

After approval, ask Codex:

```text
Set up Talivia for this project. Select or create the correct website, install the tracker,
connect revenue through a secure browser handoff, and verify that real data is arriving.
```

## ChatGPT [#chatgpt]

1. Open **ChatGPT → Settings → Apps & Connectors**.
2. Create a custom app named `Talivia`.
3. Set the MCP server URL to `https://talivia.com/mcp` and choose OAuth.
4. Save the app, then complete Talivia sign-in and consent in the browser.
5. Enable Talivia in a chat before asking it to review or finish setup.

## Claude [#claude]

1. Open **Claude → Customize → Connectors → Add custom connector**.
2. Name the connector `Talivia` and use `https://talivia.com/mcp` as the remote MCP URL.
3. Complete Talivia sign-in and consent in the browser.
4. In a conversation, open the `+` menu, choose **Connectors**, and enable Talivia.

## Claude Code [#claude-code]

Register the hosted endpoint:

```bash
claude mcp add --transport http talivia https://talivia.com/mcp
```

The first protected tool call starts browser authorization.

## Other MCP clients [#other-mcp-clients]

Use a Streamable HTTP server with OAuth discovery:

```json
{
  "talivia": {
    "type": "http",
    "url": "https://talivia.com/mcp",
    "auth": "oauth"
  }
}
```

Your client must support MCP OAuth authorization-server discovery and the browser authorization flow. If it does not, use one of the supported clients above.

## What the agent can do [#what-the-agent-can-do]

Talivia exposes focused tools for setup and analysis:

* Read a period overview with traffic, conversions, revenue, refunds, and a previous-period comparison.
* Inspect event names, event properties, action counts, unique visitors, and time series.
* Read saved goal definitions and calculate their results for the selected period.
* Read saved funnel definitions and calculate step reach and drop-off.
* Read every Talivia dimension shown in the dashboard, including channel, referrer, every UTM field, landing and exit pages, hostname, geography, browser, device, language, and visitor ID. Revenue-capable dimensions also include payments and attributed revenue.
* Read the Keywords view, which combines tracked UTM terms with connected Google Search Console and Bing Webmaster queries, clicks, impressions, CTR, position, pages, and estimated organic revenue.
* Read confirmed payments, new customers, renewals, refunds, disputes, subscriptions, and revenue attribution.
* Inspect aggregate visitor journeys or trace a specific payment from acquisition through product activity and attribution.
* Diagnose freshness, identity coverage, provider sync failures, pending checkout returns, and unattributed payments.
* Create or select a website, install the tracker, connect a payment provider through a secure handoff, and verify ingestion.

Every analytics response states the effective period, timezone, generation time, and whether the result is ready or empty. `startDate` and `endDate` accept any valid range, so an agent can request 30 days, 40 days, or exact campaign dates instead of relying on fixed presets. Empty data and a failed query are reported differently.

Talivia reports observed product and payment data, including its existing Keywords view. Google Ads account spend, ad creative, bidding keywords, and ad search terms still come from the advertising platform and should be joined with Talivia results by the agent.

For example:

```text
Analyze the last 30 days for my website. Use Talivia for product events, goals, funnels,
traffic sources, confirmed payments, customer journeys, and data quality. Combine those
results with Google Ads spend before calculating CAC or ROAS.
```

## Troubleshooting [#troubleshooting]

### The browser does not open [#the-browser-does-not-open]

Confirm that the client supports OAuth for remote MCP servers. Remove the existing Talivia entry, add it again, and retry authorization.

### The endpoint is unavailable [#the-endpoint-is-unavailable]

Open **Settings → AI agents** and check the endpoint status. A healthy endpoint shows **Ready to connect**.

### The wrong account was authorized [#the-wrong-account-was-authorized]

Revoke the connection in **Settings → AI agents**, sign in to the intended Talivia account in your browser, and connect again.

### The agent cannot see a website [#the-agent-cannot-see-a-website]

The MCP connection follows the same account and website permissions as the Talivia UI. Confirm that the signed-in account has access to that website.