# Getting Started


There are two ways to connect, and the first one needs no credential at all:

- **One-click connect** for any client that supports OAuth: point it at the
  server URL and approve in your browser. Nothing to copy, store, or rotate.
- **Connect with a token** for unattended, headless, and CI clients, and for
  clients that only accept a fixed `Authorization` header: mint a long-lived
  MCP token and put it in the client's configuration.

Both paths talk to the same server and expose the same tools. On Claude Code
and Cowork, the [Intuizi plugin](#claude-code-and-cowork-plugin) wraps the
one-click path in a single command.

## Connect in one click

The server publishes its own OAuth 2.1 metadata, so a compliant client needs
nothing but the URL:

```
https://console.intuizi.com/api/v2/mcp
```

The client discovers the Intuizi authorization server, registers itself, and
opens an Intuizi consent screen in your browser. Sign in to the console if you
are not already, check that the application name and the destination shown on
the consent screen are what you expect, and choose Approve. The connection
completes automatically and the agent can start calling tools.

{{< callout type="warning" >}}
Do not set an `Authorization` header on this path. A hardcoded header means the
client never receives the challenge that starts the handshake, so the one-click
flow never runs and the client falls back to expecting a token.
{{< /callout >}}

### Claude Code and Cowork: the plugin {#claude-code-and-cowork-plugin}

On Claude Code and Cowork the quickest route is the Intuizi plugin. It carries
the server declaration, so there is no URL to paste, and it adds a skill that
tells the agent the order these tools are meant to be called in.

```bash
/plugin marketplace add intuizi/intuizi-claude-plugin
/plugin install intuizi@intuizi
```

Then run `/mcp`, choose `intuizi`, and pick Authenticate to approve in your
browser, exactly as below. The plugin is open source at
[github.com/intuizi/intuizi-claude-plugin](https://github.com/intuizi/intuizi-claude-plugin),
so you can read what it declares before installing it.

The plugin carries the MCP server itself, so it applies to Claude Code and
Cowork. In other Claude surfaces, add the server as a connector instead.

### Claude Code: adding the server directly

If you would rather not install a plugin, add the server with no header and
authenticate in the browser:

```bash
claude mcp add intuizi --transport http https://console.intuizi.com/api/v2/mcp
```

Then run `/mcp`, choose `intuizi`, and pick Authenticate. Claude Code opens
the Intuizi consent screen in your browser. Once approved, `claude mcp list`
reports the server as connected, and it stays connected across sessions
without further approval.

### Custom connectors

Clients that add MCP servers as custom connectors take a server URL only -
there is no field for a token. The exact path differs by client, but it is
typically under a Connectors or Integrations settings section, as "Add custom
connector" (custom MCP connectors may only be available on certain plans).
Paste the URL above and approve in the browser.

### What to know about one-click connections

- Approval issues the client its own short-lived credentials (about one hour),
  which the client renews automatically for up to 60 days without
  re-approval. There is nothing to copy or store.
- Console logins and logouts do not disturb the connection.
- Changing your Intuizi password disconnects every connected application and
  every MCP token immediately - reconnect afterwards.
- To disconnect, remove the server or connector in your client, or change your
  password to sever everything at once.

The protocol-level details (discovery documents, PKCE, token lifetimes) are
documented in [Authentication](/api/v2/authentication#oauth-one-click-connect).

## Connect with a token

Some clients only accept a static `Authorization` header, and an unattended
agent that must survive with no one at the keyboard is better served by a
long-lived credential than by a flow that needs a browser. This path is fully
supported.

### 1. Mint an MCP token

MCP connections are long-lived, so they use a dedicated token type. Unlike
the [login token](/api/v2/authentication), MCP tokens are not rotated by
logins and survive console logout; changing your password revokes them.
They expire after one year or when you revoke them.

The primary path is the Intuizi console: open My Account > MCP Tokens and
choose Generate new token. The token is shown once - copy it and store it
like any credential, because anyone holding it can act on your account until
it is revoked. The same page lists your active tokens and lets you revoke
them individually.

For CLI and headless clients where opening a browser is not practical, mint
through the API instead - see
[Create MCP Token](/api/v2/authentication#post-apiv2authmcptoken) for the
full endpoint contract:

```bash
curl -X POST "https://console.intuizi.com/api/v2/auth/mcp-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'
```

The token arrives in `data.token`, and is likewise shown only once.

### 2. Connect your agent

The server speaks stateless Streamable HTTP at
`https://console.intuizi.com/api/v2/mcp`. Send the token as an
`Authorization: Bearer` header.

If your client supports OAuth, omit the header entirely and it will run the
one-click flow described above instead.

### Claude Desktop

Claude Desktop connects through the `mcp-remote` bridge. Add to
`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "intuizi": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://console.intuizi.com/api/v2/mcp",
        "--header",
        "Authorization: Bearer YOUR_MCP_TOKEN"
      ]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "intuizi": {
      "url": "https://console.intuizi.com/api/v2/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_TOKEN" }
    }
  }
}
```

### Claude Code, non-interactive

In CI, containers, and other places where no one can approve a browser
prompt, pass the token explicitly. Interactive installs should use the
one-click command above instead.

```bash
claude mcp add intuizi --transport http https://console.intuizi.com/api/v2/mcp \
  --header "Authorization: Bearer YOUR_MCP_TOKEN"
```

### OpenAI Agents SDK (Python)

```python
from agents.mcp import MCPServerStreamableHttp

intuizi = MCPServerStreamableHttp(params={
    "url": "https://console.intuizi.com/api/v2/mcp",
    "headers": {"Authorization": "Bearer YOUR_MCP_TOKEN"},
})
```

## Try it

Ask your agent, for example:

- "List my Intuizi audiences."
- "Which dataset types can my account use? Use lookup_reference."
- "Build an audience of devices seen at my POI brand X in June, wait for it
  to complete, then activate it to my S3 endpoint connection."

The `build_and_activate_audience` prompt shipped with the server walks the
agent through the full workflow in the right order.
[Preview, then Activate](/mcp/preview-and-activate) is a worked session for
the frequency filter: preview the exact device count a visit-frequency range
would export, then activate exactly that range with the server proving the
two match.
[Automate with an AI Agent](/guides/automate-with-an-ai-agent) is the guide-form
version of that workflow: the lookup, create, poll, activate loop, with the
idempotency and rate-limit rules an unattended run needs.

For long-running builds, [webhooks](/concepts/webhooks) are the efficient
completion signal: register a receiver in the console and the
`audience.completed` / `activation.completed` events push the finished
resource to your server, so the agent does not have to hold a polling loop.
Polling stays available as the fallback when no webhook receiver exists.

## Behavior and limits

- Tool calls consume the same per-token rate limits as direct API calls: by
  default 120 reads/min, 30 writes/min, and 120 MCP requests/min. On a 429 the
  error text includes the `Retry-After` seconds.
- The create tools accept an `idempotency_key` argument so agents can retry
  creates safely - same semantics as the `Idempotency-Key` header (see
  [Idempotency](/concepts/idempotency)).
- Tool errors carry the API's error envelope verbatim - see
  [Errors](/concepts/errors) for shapes and codes.
- Alongside tools the server exposes a fixed set of these docs pages as
  read-only resources (`resources/list`, `resources/read`) - see
  [Resources](/mcp/tools-reference#resources). Reading one costs no API call
  and returns no account data.
- To disconnect a token-connected agent permanently, revoke its token on the
  My Account > MCP Tokens page in the Intuizi console, which revokes tokens
  individually. For the headless path, use
  [Revoke MCP Tokens](/api/v2/authentication#post-apiv2authmcptokenrevoke) -
  note the API revoke is all-or-nothing: it revokes every MCP token on the
  account at once. For one-click connections, remove the server or connector
  in the client instead. Changing your Intuizi password disconnects everything
  at once - every token and every one-click connection.