> ## 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.

# Connect

> Point your assistant at the Ziplined MCP server.

Connect an assistant to your workspace in one step. Pick your client below.

> [tab] Claude Code
>
> **1. Create a key**
>
> In the Ziplined app, go to **Settings, Integrations, API keys**. Create a key with
> scope `read`. It starts with `zpl_` and is shown once.
>
> **2. Add the server**
>
> ```bash theme={null}
> claude mcp add --transport http ziplined https://api.ziplined.io/mcp \
>   --header "Authorization: Bearer zpl_..."
> ```
>
> **3. Ask something**
>
> Try "who engaged with my posts last week that I have never messaged?". See
> [First questions](https://docs.ziplined.io/mcp/first-questions.md).

> [tab] Claude.ai
>
> **1. Add a custom connector**
>
> Go to **Settings, Connectors, Add custom connector**. URL
> `https://api.ziplined.io/mcp`, authentication **OAuth**.
>
> **2. Pick your organization**
>
> Clerk asks you to pick an organization at the consent screen. That organization
> decides the workspace.
>
> **3. Ask something**
>
> The connector shows all ten tools. See [First questions](https://docs.ziplined.io/mcp/first-questions.md).
>
> > [!WARNING]
> >
> > A token without an organization is a 401 `workspace_required`. Pick a workspace in
> > Ziplined and connect again.

> [tab] Cursor
>
> **1. Create a key**
>
> In the Ziplined app, **Settings, Integrations, API keys**, scope `read`.
>
> **2. Edit \~/.cursor/mcp.json**
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "ziplined": {
>       "url": "https://api.ziplined.io/mcp",
>       "headers": { "Authorization": "Bearer zpl_..." }
>     }
>   }
> }
> ```
>
> **3. Reload Cursor**
>
> The server appears under MCP with its tools listed.

> [tab] Other
>
> **1. Use the endpoint**
>
> The server is a standard stateless Streamable HTTP MCP server. Any client on that
> transport works.
>
> ```
> URL     https://api.ziplined.io/mcp
> Header  Authorization: Bearer zpl_...
> ```
>
> **2. Check it by hand**
>
> ```bash theme={null}
> npx @modelcontextprotocol/inspector
> ```
>
> Pick transport Streamable HTTP and paste the URL and header. Two calls in a row
> without a session header should both succeed.
>
> > [!NOTE]
> >
> > The transport is stateless. There is no `Mcp-Session-Id`, no GET and no DELETE.

> [accordion] OAuth or an API key
>
> Use **OAuth** when a person connects their own assistant. The token carries who they are,
> they get every scope their workspace allows, and there is no secret to lose.
>
> Use an **API key** when a program connects, or when the client cannot do the OAuth
> handshake. The key carries fixed scopes, so a `read` key sees seven of the ten tools. The
> other three are absent from `tools/list`.
>
> Either way the workspace comes from the credential. In Claude.ai you can also pick
> authentication **static\_headers** with `Authorization: Bearer zpl_...`. That needs an org
> admin, and the caller is then a key rather than a person.
>
> The 401 handshake points at `/.well-known/oauth-protected-resource`, which names Clerk as
> the authorization server.

## Limits and errors

| Topic | Value |
| - | - |
| Plan | Behind the `mcp` feature |
| Rate limit | 60 requests a minute per credential |
| Tool errors | `isError: true` with a `code` |

The REST API and MCP share one rate limit bucket per credential. A missing plan feature is
a 402 with an upgrade URL.

> [accordion] Which errors are tool errors
>
> An error inside a tool is a tool error, not a transport error. `structuredContent` carries
> `invalid_argument`, `forbidden`, `not_found`, `conflict`, `rate_limited` (with
> `retry_after` in seconds) or `internal_error`.
>
> Only missing or invalid authentication is an HTTP status. The client has to react to it
> with an OAuth handshake, so it answers 401 with
> `WWW-Authenticate: Bearer resource_metadata="..."`.
>
> The full list of codes is on [Errors](https://docs.ziplined.io/api/errors.md).


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