# Set up a Keiki agent

Use this guide when someone asks you to build an agent on Keiki, connect Keiki, or put an agent on SMS, iMessage, WhatsApp, Telegram, Slack or email. Aim to finish the whole setup from this one prompt.

## Before you start

- Keiki is invite-only. If the person is not in yet, you can request access for them from this conversation (step 2) and pick up where you left off once they are.
- Never ask for an API key or channel token in chat. Credentials go through OAuth, the dashboard, or an environment variable the person sets.
- Ask before anything that spends money or reaches real people: buying a line, connecting a production channel, or messaging contacts.

## 1. Ask what to build

Ask once, in one message, with your best guesses filled in:

- What the agent does and who will message it.
- The channel: iMessage, WhatsApp, Telegram, Slack, email, or the HTTP API only. SMS lines are bought and attached in the dashboard.
- Systems it must reach (an MCP server, an OpenAPI spec, a webhook) and anything it must never do without a person.
- Whether they already use Keiki. If not, ask in the same message for their name, work email, phone and company, so you can request access without another round trip.

## 2. Request access

Skip this if the person is already in. Otherwise:

1. Get their OK, then send `POST https://onkeiki.com/api/webapp/auth/waitlist` with JSON `{ "email", "name", "org", "phone", "note", "source": "agent" }`. Use your one-line summary from step 1 as `note`. All fields but `source` are required. `{ "ok": true }` means the request is in, and a repeat is safe. On 400, fix the field it names. On 429, wait `retryAfterSeconds`. If you cannot send HTTP requests, give them [https://onkeiki.com/signup](https://onkeiki.com/signup) with the fields filled in from their answers.
2. Tell them the Keiki team reviews requests and sends an invite link. To move faster they can book a call at [cal.com/nizzy](https://cal.com/nizzy) or [cal.com/team/orchid/onboarding](https://cal.com/team/orchid/onboarding). A teammate already on Keiki can invite them now from the organization's Members settings.
3. While they wait, draft the agent: pick the template or write the system prompt, and write the test messages for step 5. Show them the draft.
4. Once they open the invite and say they are in, continue with step 3. Do not ask the step 1 questions again.

## 3. Connect to Keiki

Prefer MCP. Add `https://onkeiki.com/mcp` as a remote Streamable HTTP server. The client opens a browser where the person signs in, picks the organization and approves. There is no client id or secret to copy.

- Claude Code: `claude mcp add --transport http keiki https://onkeiki.com/mcp`
- Codex: `codex mcp add keiki --url https://onkeiki.com/mcp`
- Cursor: add `{ "mcpServers": { "keiki": { "url": "https://onkeiki.com/mcp" } } }` to `.cursor/mcp.json`
- VS Code: `code --add-mcp '{"name":"keiki","type":"http","url":"https://onkeiki.com/mcp"}'`
- Any other client: the [MCP server card](https://onkeiki.com/.well-known/mcp.json) has the transport and OAuth metadata.

An organization without a plan can connect, but its agents run capped (a cheap model, fewer steps, no MCP tools) until the person adds one at [https://onkeiki.com/settings?tab=billing](https://onkeiki.com/settings?tab=billing) (see [pricing](https://onkeiki.com/pricing.md)).

Call `current_context` to confirm the organization and role; owners and admins can create agents and deployments.

Without MCP, the person creates an org-wide API key at [https://onkeiki.com/settings?tab=api-keys](https://onkeiki.com/settings?tab=api-keys) and exports it as `KEIKI_API_KEY`. Use the [developer API](https://onkeiki.com/openapi.json) and [partner deployments](https://onkeiki.com/docs/partner-deployments.md) instead of the tools below.

## 4. Build the agent

Call `list_agent_templates` and pick the closest template, or use the system prompt you drafted. Create the agent with `deploy_agent` and no channels yet, choosing a stable `external_ref`. Every later `deploy_agent` call with that `external_ref` updates the same agent:

```json
{ "external_ref": "front-desk", "agent": { "template": "<template id>", "name": "Front desk" } }
```

The body is the one [partner deployments](https://onkeiki.com/docs/partner-deployments.md) documents; `agent` can be a full spec instead of a template. If the response lists `deployment.missingSecrets`, tell the person which secrets to add in the dashboard before going live.

## 5. Test it

Call `talk_to_agent` with the agent's name and a real first message, then two or three follow-ups that exercise its tools and limits. Nothing is delivered to a real line, but the agent's own tools run for real. Change the agent with `deploy_agent` and test again until the replies are right.

## 6. Go live

Call `list_channel_types` for the fields each channel needs. Then call `deploy_agent` again with three things: the same `external_ref`, `"agent": {}` to leave the agent unchanged, and a `channels` list. Each channel reports `connected`, `needs_payment`, `error` or `skipped`. An `imessage` channel provisions a paid line, so confirm first. For the HTTP API only, use `{ "type": "api" }` and follow the [agent API guide](https://onkeiki.com/docs/agent-api.md). SMS is not a deployment channel: the person buys and attaches the line on the dashboard's Channels page.

Call `get_deployment` with `{ "externalRef": "<the same external_ref>" }` and check that every channel you asked for is listed as `connected`. An iMessage channel shows its `phoneNumber`.

## 7. Report

Tell the person:

- The agent's name.
- How to reach it, such as the number to text or the bot to message, and suggest they send the first message themselves.
- Anything they still have to do, such as approving a purchase, adding a secret or verifying a number.
- At most two next steps.

## Help

- [Developer portal](https://onkeiki.com/developers) and [docs](https://onkeiki.com/llms.txt)
- [MCP server](https://onkeiki.com/docs/mcp.md) and [Code Mode](https://onkeiki.com/docs/mcp-codemode.md)
- [auth.md](https://onkeiki.com/auth.md) for OAuth details