---
name: zipq
description: >-
  Discover and run workflows published through ZipQ's remote MCP server. Use
  when the user mentions ZipQ, asks to connect Claude or Codex to ZipQ, wants
  to browse public ZipQ workflows, or wants to inspect or run a published ZipQ
  capability. Connect through OAuth when the ZipQ MCP tools are unavailable;
  inspect workflow contracts before starting them and retrieve only the
  artifacts returned by the run.
metadata:
  version: "0.1.0"
---

# ZipQ MCP

ZipQ exposes published, guardrailed workflows through one remote Streamable
HTTP MCP endpoint:

`https://agents.zipq.ai/mcp`

This file is setup and compatibility guidance. After the MCP connection is
available, treat the server's current tool schemas, tool descriptions,
structured `nextAction` hints, and `zipq://guide` resource as authoritative.
They are maintained remotely and may be newer than an installed copy of this
file. Do not ask the user to reinstall or reconfigure ZipQ merely to refresh
operating guidance; reconnect the existing MCP server or begin a new client
session when a client has cached older metadata.

The MCP client authenticates the user through ZipQ OAuth. Connecting to the
server does not grant membership in a publisher's agent workspace or access to
private conversations, credentials, files, or provider connections.

## Setup

First check whether these ZipQ MCP tools are already available:

- `search_workflows`
- `describe_workflow`
- `start_workflow`
- `get_workflow_run`
- `read_workflow_artifact`

If they are available, use them and do not modify MCP configuration.

If they are unavailable and the user asked to connect or use ZipQ, configure
the current client. Preserve unrelated MCP configuration.

When browsing `https://zipq.ai` with a WebMCP-capable agent, the homepage also
offers `get_zipq_mcp_connection`. That read-only site tool returns the same MCP
endpoint, OAuth requirement, expected tools, and client-specific setup guidance.
`start_zipq_mcp_install` is retained as a compatibility alias with the same
result.
Treat its result as an installation offer: show it to the user and obtain
consent before changing the host's MCP configuration. Calling the site tool
does not itself install or authorize the server.

### Claude Code

```sh
claude mcp add --transport http zipq https://agents.zipq.ai/mcp
claude mcp login zipq
```

Verify with:

```sh
claude mcp get zipq
```

If the server is already configured, do not add it again; run
`claude mcp login zipq` only when authentication is required.

### Codex

Add this table to the user-level `~/.codex/config.toml`, or to
`.codex/config.toml` when the user explicitly wants project-scoped setup:

```toml
[mcp_servers.zipq]
url = "https://agents.zipq.ai/mcp"
auth = "oauth"
default_tools_approval_mode = "writes"
```

Then authenticate and verify:

```sh
codex mcp login zipq
codex mcp list
```

Do not overwrite the configuration file. Add or update only the
`mcp_servers.zipq` table, and do not place access tokens in the file.

OAuth may open a browser. Let the user complete login and consent; never ask
them to paste browser cookies, refresh tokens, or another client's credentials.

## Workflow

Use this sequence for a published ZipQ workflow:

1. Call `search_workflows`. Describe the user's desired outcome in a natural
   intent phrase; ZipQ semantically matches public workflow cards using the
   title, summary, and safe operational metadata. Use an empty query only to
   browse recent public workflows. Follow `nextCursor` only for the newest-first
   browse path. Do not repeat an equivalent search unless the query or cursor
   changes.
2. Call `describe_workflow` for the selected result. Treat its pinned version,
   `inputSchema`, and `exampleInput` as authoritative. Never guess required
   input fields.
3. Confirm that the workflow matches the user's request. If starting it would
   create an external side effect the user has not requested, obtain the
   user's approval before continuing.
4. Call `start_workflow` with the selected `agentId`, `workflowId`, validated
   input, and a new idempotency key. Reuse the same idempotency key when
   retrying the same logical start; use a new key for a genuinely new run.
5. Poll `get_workflow_run` until the status is `completed`, `failed`, or
   `cancelled`. `queued`, `running`, `waiting`, and `paused` are not terminal.
   Wait briefly between unchanged polls and do not narrate every poll.
6. On completion, collect every artifact reference. Follow
   `result.nextArtifactCursor` with `artifactCursor` until it is empty.
7. Call `read_workflow_artifact` for each artifact the task needs. Follow
   `chunk.nextOffset` with `offset` until `eof` is true. Preserve the reported
   content type and do not invent access to unreturned artifacts.

Keep interactive use responsive: start the run, report the run id when useful,
and poll without treating a non-terminal status as a failure.

## Connected Agent Tools

`search_agent_tools` and `describe_agent_tool` can describe provider tools
connected to agents the authenticated user may access. These entries are
catalog-only on the public ZipQ MCP server. Do not attempt to execute them
directly; use a published workflow that wraps the capability.

## Failure Handling

- Authentication failure: verify the `zipq` server, then run the client's MCP
  login flow. Do not replace OAuth with a pasted bearer token.
- Invalid input: call `describe_workflow` again and validate against the pinned
  schema before retrying.
- Failed or cancelled run: stop polling and report the run status and returned
  error without claiming completion.
- Inaccessible workflow or artifact: do not infer access from an id. ZipQ
  rechecks publication, caller authorization, source sharing, and run ownership
  on every request.
- Retried start: reuse the original idempotency key only when it is the same
  intended invocation.

For human-readable discovery outside MCP, browse
`https://zipq.ai/marketplace`. Running a workflow still requires ZipQ OAuth.