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

# Set up your agent

> Start setup, connect an agent to a hosted Kiwi project, and prepare its existing developer workspace.

Use the agent environment you already have to connect to a hosted Kiwi project. Kiwi stays hosted; this guide does not install a local Kiwi client or server.

## Connection-only prompt brief

This short brief is for the existing connection-only helpers on `/app` and `/app/mcp`. The `/app/get-started` prompt also prepares the current developer workspace after the hosted connection is verified.

Paste this into your agent:

```text wrap theme={null}
Help me connect my existing agent environment to a hosted Kiwi project through its supported MCP connection. Ask me one question at a time and follow:
https://docs.kiwiflow.io/ai-quickstart.md
https://docs.kiwiflow.io/remote-mcp.md
```

## Start with Get started

From the public Kiwi landing page, choose **Get started**. Signed-out visitors continue through Clerk's hosted signup and return to `/app/get-started`; signed-in visitors go straight to the choice. Choose **Set up with an agent** to reveal a prompt for the current developer workspace, or **Continue manually** to open the existing project setup at `/app`. You can return to the choice through **Get started** later.

First-time setup initializes an organization and **My first project** through the hosted app. It does not publish a workflow. Choosing agent setup only reveals the prompt; it does not connect the agent. After you paste and run the prompt and complete OAuth sign-in in the agent client, it asks the agent to verify the current organization, exact project, role, and published workflows through actual MCP responses, then update appropriate existing workspace guidance. It preserves unrelated instructions and reports when workspace files are unavailable. This purpose can prepare a workflow proposal when a successful `list_workflows` response contains no published workflows; an eligible Admin reviews and publishes it in the Kiwi app. It does not create a workflow, run, credential, invitation, membership, or billing change.

The helpers already available from [Projects home](https://www.kiwiflow.io/app) and [MCP & access](https://www.kiwiflow.io/app/mcp) stay connection-only: they connect and verify access without asking to edit developer workspace guidance.

## Choose your organization and project

* **New to Kiwi:** choose [Get started](https://www.kiwiflow.io/get-started), create an account through hosted Clerk signup, then choose agent or manual setup.
* **Joining a team:** accept the organization invitation, then open the project you were invited to use. Organization membership does not grant access to every project. If it is missing, ask a project Admin for access.
* **Already use Kiwi:** select an organization in the app, then choose a project you can access inside the setup helper.

See [Organizations and accounts](https://docs.kiwiflow.io/organizations.md) for membership and role details. Complete sign-in, invitation acceptance, and any permission changes in Kiwi.

## Copy the project's setup prompt

In the signed-in app, select the intended organization. Open **Set up your agent → Copy setup prompt** from [Projects home](https://www.kiwiflow.io/app) or the global [MCP & access page](https://www.kiwiflow.io/app/mcp). Choose the project inside the helper. If only one project is available, it is selected for you; otherwise, choose the intended project.

The prompt revealed by **Set up with an agent** at `/app/get-started` uses the same current connection details and selection rules, with the developer-workspace purpose described above. The `/app` and `/app/mcp` prompts remain connection-only.

Paste the copied prompt into your agent. It contains the canonical MCP endpoint and the selected organization's and project's names and IDs as JSON data. Those values identify the connection; they are not credentials. The prompt contains no access token, key, password, or secret.

Ask your agent to add the connection through the MCP settings supported by that agent environment. Use the endpoint and selected project details from the copied prompt. Preserve other configured servers and ask before replacing a conflicting Kiwi entry. If your client stores MCP settings in a file, follow that client's instructions. This connection uses Kiwi's hosted service through OAuth. Complete sign-in in the client and select the organization that contains the project. No API key is required for OAuth.

Verify the connection with actual MCP responses: call list\_projects, match the exact project ID from the setup prompt, then call list\_workflows for that project. Report what those calls returned. If the exact project is absent, either read fails, access is denied, or the calls are unavailable, explain the specific blocker and stop; a failed read is not an empty workflow list. Copying the prompt or seeing documentation does not prove an authenticated connection.

Neither prompt purpose creates or publishes a workflow or starts a run. MCP cannot publish a workflow, look up members, identify the current user with whoami, report a CI check, or make a human decision. Any suitable existing published workflow, including a custom workflow, is valid for general developer-workspace setup; do not require one named Development. Only when list\_workflows succeeds and returns no published workflow does the developer-workspace prompt prepare a proposal and give an eligible Admin the project workflow page at `/app/projects/{encodedProjectId}?view=workflows`. The prompt builds the absolute browser link from the canonical MCP service origin; keep the MCP endpoint and OAuth audience unchanged. For the optional Development task below, use a published Development workflow. The [manual quickstart](https://docs.kiwiflow.io/quickstart.md) and [workflow guide](https://docs.kiwiflow.io/workflows.md) explain that path.

## Optional: track a Development task

After connection is verified, use this only when you want a specific task tracked in Kiwi. Describe the task in plain language. Starting a run is a separate choice from setup.

```text wrap theme={null}
Before any run mutation, read and follow:
https://docs.kiwiflow.io/for-agents.md
https://docs.kiwiflow.io/workflows.md
https://docs.kiwiflow.io/ci-reporting.md

I want Kiwi to track this development task: [describe the goal in plain language].

Before starting a run, verify the selected project's exact ID in list_projects and inspect its published workflows with list_workflows. Use only the project's existing published Development workflow. If access or Development is unavailable, stop and tell me the next step. A project Admin must publish a missing Development workflow in the Kiwi app; do not create or change one. If a human QA assignment is required, explain it when relevant and help me confirm an eligible person through the project Members area or an Admin. Do not invent people, IDs, checks, or results.

If Development is published and the available actions permit it, start one run for this task using the returned project and workflow data. Prepare the Plan and use only actions the current run allows. Stop for the designated owner to decide the Plan in the app before implementation. Follow the actual candidate, check, reviewer, and Handoff requirements, and pause for each human decision. Do not bypass a gate.
```

An agent may submit a Plan when the run allows it, but the designated owner accepts it in the app. The reviewer makes Human acceptance in the app. An MCP tool receipt does not mean either decision passed. If a task needs a human-attested check and the agent cannot confirm a real eligible reporter, ask a project Admin to resolve the assignment; MCP has no member-lookup tool.

## Optional: prepare team or CI setup

For team access, ask the agent to prepare steps from [Organizations and accounts](https://docs.kiwiflow.io/organizations.md):

```text wrap theme={null}
Help me prepare team access for this Kiwi project. Read
https://docs.kiwiflow.io/organizations.md and explain the difference between
organization invitations and project roles. Give me a read-only checklist. I
will make any membership or role changes in Kiwi myself. Do not send invitations
or change roles or billing.
```

For CI, use [Connections](https://docs.kiwiflow.io/connections.md) and [CI reporting](https://docs.kiwiflow.io/ci-reporting.md):

```text wrap theme={null}
Help me prepare CI check reporting for this project's existing pipeline. Read
https://docs.kiwiflow.io/connections.md and
https://docs.kiwiflow.io/ci-reporting.md. Explain the required inputs and steps.
Prepare guidance only; do not issue credentials, change CI settings, or create,
request, or store secrets. I will complete Admin and secret-store actions.
```

For a manual first run in the hosted app, see the [quickstart](https://docs.kiwiflow.io/quickstart.md). For exact agent actions in an existing run, use the [Agent guide](https://docs.kiwiflow.io/for-agents.md). For check results, see [CI reporting](https://docs.kiwiflow.io/ci-reporting.md).


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