> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ziplined.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> How an AI agent sets up Ziplined and works with leads, in tool calls.

This page is for agents and for the people who build with them. It walks the setup of a
workspace as the tool calls an agent makes on the Ziplined MCP server, and lists the rules
the server enforces.

Ziplined is LinkedIn engagement intelligence. It finds the people who engage around you and
your market and keeps the ones who fit your ideal client profile (ICP). It does not write or
send LinkedIn messages.

## Install

| Client | How |
| - | - |
| Claude, ChatGPT | Add a custom connector with URL `https://mcp.ziplined.io/mcp` and OAuth. See [Connect](https://docs.ziplined.io/mcp/connect.md). |
| Claude Code | `claude mcp add --transport http ziplined https://mcp.ziplined.io/mcp`, then `/mcp` to sign in. |
| Codex | `codex mcp add ziplined --url https://mcp.ziplined.io/mcp`, then `codex mcp login ziplined`. |
| Cursor | `~/.cursor/mcp.json`: `{"mcpServers":{"ziplined":{"url":"https://mcp.ziplined.io/mcp"}}}` |
| VS Code | `.vscode/mcp.json`: `{"servers":{"ziplined":{"type":"http","url":"https://mcp.ziplined.io/mcp"}}}` |

The Ziplined app shows the same steps on the AI agent page, with one-click install links.

The repository also ships a plugin for Claude Code and Cursor under `packaging/ziplined`: the
MCP server plus a skill (`skills/ziplined/SKILL.md`) that teaches the rules below.

> [!NOTE]
>
> Sign-in is OAuth. The workspace comes from the account you sign in with. There is no key to
> paste and no workspace id to pass.

## Setup in tool calls

**1. Ask where the workspace stands**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
get_account {}
```

The answer carries `next_step`. Follow it.

* `next_step.tool` names the tool to call next, with a `reason` and a `cost`.
* `next_step.url` is a page in the app. The company website, the LinkedIn profile and the
  team are set there, never through a tool. Give the user the link.
* `next_step.tool: "search_people"` means setup is done.

**2. Set the ideal client**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
get_icp {}
save_icp { "include": { ... }, "exclude": { ... } }
```

`save_icp` replaces the whole profile, so send back every rule to keep. The answer
estimates how many people it would include. Free.

**3. Add a source**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
save_source { "type": "keyword", "display_name": "RevOps", "keyword_query": "revenue operations" }
```

The first call adds nothing. It answers `needs_confirmation`, a `summary`, a `cost` with
an `estimate` and a `ceiling`, and a `confirm_id`. After the user agrees:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
save_source { "type": "keyword", "display_name": "RevOps", "keyword_query": "revenue operations", "confirm_id": "..." }
```

**4. Make a view**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
get_filter_options {}
save_view { "name": "Outreach", "kind": "filters", "filter": { ... } }
get_view { "view": "Outreach" }
```

A `hand_picked` view is filled with `add_to_view` instead.

**5. Connect a destination**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
connect_destination { "provider": "slack" }
```

Give the user the `connect_url`. They finish in the app. Then:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
list_destinations {}
test_destination { "destination_id": "..." }
```

Webhook and email destinations use `save_destination` and need no link. It asks for a
`confirm_id` first, and email goes only to members' addresses or their company domain.

**6. Sync the view**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
save_sync { "view": "Outreach", "destination_id": "...", "enabled": true }
```

Read the `effects` back to the user. Adding `add_email`, `add_phone` or
`lookup_current_members` costs credits and asks for a `confirm_id` first. Contact
details are looked up for Leads only: 5 credits per verified work email.

**7. Work the people**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
search_people { "view_id": "..." }
get_person { "person_id": "..." }
log_outreach { "person_id": "...", "channel": "linkedin_message" }
update_person { "person_ids": ["..."], "status": "not_a_lead", "reason": "customer" }
```

Argument values here are examples. The tool schemas list the valid values.

## Rules the server enforces

### Summary first, confirm second

A tool that costs credits or removes something changes nothing on the first call. It answers
`needs_confirmation: true`, a `summary`, a `confirm_id` and, when it costs, a `cost` with an
`estimate` and a `ceiling`. The user approves the ceiling; work stops there and the result
states the real cost. Call again with the same arguments plus the `confirm_id`, within 10
minutes.

This applies to `save_source`, `save_sync` with contact details, `save_view` when the filter
of a synced view changes, `send_people`, `remove_from_view`, `update_person` on more than 25
people, and `delete_view`, `delete_source` and `delete_destination`. `refresh_data` on a
whole audience asks for `confirm: true` instead and costs no credits.

### Effects on syncs

* Starting a sync sends nothing for the people already in the view. They are the baseline.
  Only people who enter after that are sent, each once.
* Changing the filter of a synced view sets a new baseline. People who enter because of the
  change are not sent.
* Someone who leaves a view and comes back is not sent again.
* The worker checks every 10 minutes. Sends are bundled per frequency and send hour.
* Not a fit, Peer or Customer removes a person from every hand-picked view and sync.
* Deleting a view stops its syncs.

To send the people already in a view, use `send_people`.

### Secrets never go through a tool

Slack, Clay, Google Sheets, HeyReach, Instantly and Waalaxy connect through the link from
`connect_destination`. It works once, for this user, within 15 minutes. An agent never asks
for a webhook URL, API key, password or OAuth code.

### Plan and credits

Every workspace can connect. A tool the plan does not include answers `feature_not_in_plan`;
credits that are used up answer `insufficient_credits`. Both carry a `next_step` that points at
the app.

A credit pays for one item: 1 per post, reaction, comment, profile visit or new follower,
and 5 per verified work email of a Lead. `get_account` splits what this period cost in
`credits_used`. Put a `cost` to the user in those words, never as a number of people. See
[Credits](https://docs.ziplined.io/credits.md).

## The tools

30 tools. [Tools](https://docs.ziplined.io/mcp/tools.md) has the arguments and hints of each.

| Object | Tools |
| - | - |
| Account | `get_account` |
| People | `search_people`, `get_person`, `update_person`, `log_outreach` |
| Companies | `search_companies`, `get_company` |
| Posts | `list_posts`, `get_post`, `get_insights` |
| Views | `list_views`, `get_view`, `save_view`, `delete_view`, `add_to_view`, `remove_from_view`, `get_filter_options` |
| Syncs | `save_sync`, `send_people` |
| Sources | `list_sources`, `save_source`, `delete_source` |
| Ideal client | `get_icp`, `save_icp` |
| Destinations | `list_destinations`, `connect_destination`, `save_destination`, `test_destination`, `delete_destination` |
| Runs | `refresh_data` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.