# Build with an AI agent

> Use Orkosi from inside ChatGPT, Claude, Cursor or any AI assistant. The agent signs you up, gets an API key and creates and runs your product through the public API or the MCP server.

Source: https://support.orkosi.com/docs/ai-agents

You do not have to leave your assistant to build with Orkosi. An AI agent can create your account, get an API key in the same call, create a product and describe the work as tasks. Orkosi then plans, builds, tests, deploys and hosts it, and the agent reads progress back. This page is written for the person setting it up; the agent reads the [public API](https://support.orkosi.com/docs/public-api) and the OpenAPI document on its own.

## What the agent can do
- **Sign you up.** One call creates your account and workspace on the free plan with its signup credits, sends you a verification email and returns the key. You set a password later from the "forgot password" link, so the agent never holds one.
- **Create and manage products.** Name it, describe it, pick a type (`saas`, `informational`, `shopify`, `blog`). It gets a URL at once.
- **Describe the work as tasks.** "Add a login page", "connect Stripe", "write the pricing page". Each task is a work order Orkosi builds; it is charged in credits when it runs.
- **Read the state.** Who am I, which products exist, what each task is doing, what the workspace has spent.

What it cannot do with the key it gets: create more keys, change billing, invite people or touch hosting settings. Those stay in the hub, signed in as you.

## Quick start: two minutes, no key in the chat
1. Copy the connector address: `https://orkosi.com/api/v1/public/mcp` (also in the app under **Settings → API keys** and **Connect an AI assistant**, with a copy button).
2. Add it as a connector in your assistant (steps per assistant below) and sign in to Orkosi when it asks. Choose **Approve**.
3. Ask in plain words: "list my Orkosi products", "create a task on my notes app to add a contact page", "what is task 1234 doing?".

The assistant now calls Orkosi from its vendor's servers, so nothing is blocked and you never paste an API key into a chat. To make sure it uses the connector, start a chat with:

```text
Use the Orkosi connector (MCP tools) for everything about my Orkosi products and tasks.
Do not call the Orkosi API with curl or code from your sandbox: the sandbox cannot reach it, and never ask me for an API key.
If the Orkosi tools are not available, tell me to add https://orkosi.com/api/v1/public/mcp as a custom connector and sign in.
```

## Claude
Claude speaks the Model Context Protocol, and Orkosi signs it in with one click: no API key or product id to copy.

**claude.ai, Claude desktop and Claude mobile**

1. On claude.ai open **Settings → Connectors → Add custom connector**.
2. Paste the address `https://orkosi.com/api/v1/public/mcp` and choose **Add**.
3. Choose **Connect**. Orkosi opens; sign in and choose **Approve**.
4. In a chat, make sure Orkosi is switched on in the tools menu.

A connector added on claude.ai also works in the desktop and mobile apps. On Team and Enterprise plans an owner adds it once for the organization (**Organization settings → Connectors**), then each person connects it.

Ask Claude "list my Orkosi products" or "create a task on my product to add a contact page": it finds the product by its name itself.

**Claude Code**

```bash
claude mcp add --transport http orkosi https://orkosi.com/api/v1/public/mcp
```

Then type `/mcp` in Claude Code, pick **orkosi** and sign in. To use a key instead of the sign-in (for scripts and CI), create one on **Connect an AI assistant** and add it as a header:

```bash
claude mcp add --transport http orkosi https://orkosi.com/api/v1/public/mcp \
  --header "Authorization: Bearer $ORKOSI_API_KEY"
```

What the connection may do: see your products and tasks, create products and tasks (tasks use credits when they run) and read what the workspace has spent. It cannot create keys, change billing, invite people or change hosting. To disconnect, revoke its key ("Claude connector") in **Settings → API keys**.

**Assistants without sign-in.** Some assistants ask for an API key instead. On the **Connect an AI assistant** page, **Create a key for my assistant** makes one with the same limited permissions, shown once with a copy button. The key goes in the header `Authorization: Bearer <key>`, set in the assistant's connector settings, never in a chat message.

**Local stdio server:** a stdio server exists for teams that run the Orkosi code; the remote connector above is the one to use from a laptop. Its configuration, for completeness:

```json
{
  "mcpServers": {
    "orkosi": {
      "command": "node",
      "args": ["backend/scripts/orkosi-mcp.js"],
      "env": { "ORKOSI_API_KEY": "ak_..." }
    }
  }
}
```

No account yet? Claude can call `POST https://orkosi.com/api/v1/public/signup` first (see [Sign up](https://support.orkosi.com/docs/public-api#signup)) and use the key it answers.

## ChatGPT
**Connector (recommended).** ChatGPT connects to remote MCP servers in developer mode (Plus, Pro, Business, Enterprise and Edu):

1. Open **Settings → Apps & Connectors → Advanced settings** and turn on **Developer mode**.
2. Back in **Apps & Connectors**, choose **Create**. Name it Orkosi, paste `https://orkosi.com/api/v1/public/mcp`, authentication **OAuth**.
3. Sign in to Orkosi and choose **Approve**.
4. In a chat, pick Orkosi from **+ → More** (developer mode) and ask in plain words.

Orkosi also answers the `search` and `fetch` tools ChatGPT's deep research uses, so it can look through your products and tasks.

**Custom GPT with actions.** A custom GPT can call the API from OpenAI's servers too: add an action that imports `https://orkosi.com/api/v1/public/openapi.json` and uses **API key, Bearer** authentication with a key from **Connect an AI assistant**. The key lives in the action's settings, never in the chat.

## Codex
```bash
codex mcp add orkosi --url https://orkosi.com/api/v1/public/mcp
codex mcp login orkosi
```

The login opens the Orkosi sign-in in your browser; approve it. With a key instead: `codex mcp add orkosi --url https://orkosi.com/api/v1/public/mcp --bearer-token-env-var ORKOSI_API_KEY`.

## Cursor, Windsurf and other MCP clients
Any client that takes a remote MCP server works the same way: add the address `https://orkosi.com/api/v1/public/mcp`; clients with OAuth open the Orkosi sign-in, the others take an API key as `Authorization: Bearer <key>`. The tools are:

| Tool                        | What it does                                             |
| --------------------------- | -------------------------------------------------------- |
| `orkosi_whoami`             | Workspace, plan, scopes, credit balance, product count   |
| `orkosi_list_products`      | The products of the workspace                            |
| `orkosi_create_product`     | Create a product (name, description, slug, product type) |
| `orkosi_get_product`        | State, lifecycle and URL of one product                  |
| `orkosi_get_product_status` | Builds, deploys, environments and tasks of one app       |
| `orkosi_update_product`     | Rename, describe, pause, resume or archive               |
| `orkosi_archive_product`    | Archive (nothing is deleted)                             |
| `orkosi_list_tasks`         | Tasks with progress, optionally of one product           |
| `orkosi_create_task`        | A work order on a product                                |
| `orkosi_get_task`           | Status and resolution of one task                        |
| `orkosi_costs`              | Spend summary                                            |
| `search`                    | Products and tasks whose words match (deep research)     |
| `fetch`                     | One product or task by the id `search` answered          |

## Why curl from the chat fails
When an assistant runs code in its own sandbox (Claude's code execution, ChatGPT's code tools) and calls `https://orkosi.com/api/...` with curl, the sandbox's network proxy refuses it ("destination not approved", or a 403 from the proxy). That request never reaches Orkosi. The connector above avoids it: connector calls go from Anthropic's or OpenAI's servers, not from the sandbox.

If you still want the sandbox to call the API (for example a script Claude writes and runs), allow the domain:

- **Claude Free, Pro and Max:** **Settings → Capabilities → Code execution and file creation**: turn on **Allow network egress** and add `orkosi.com` to the allowed domains (or choose all domains).
- **Claude Team and Enterprise:** an owner does the same in **Organization settings → Capabilities**.

Even then, keep the key out of the chat: put it in the connector or action settings, and revoke any key that was pasted into a conversation (**Settings → API keys → Revoke**).

## Grok, Gemini, Perplexity and plain HTTP
Assistants without MCP or actions can still call the API as HTTP. Point them at the OpenAPI document; the `agent.client` field of the signup body tells Orkosi which assistant created the account so you can recognise the key in **Settings → API keys** later.

## Limits and safety
- Signup is rate limited per IP address and per email, and one account per email.
- The key is rate limited per plan, with `X-RateLimit-*` headers on every answer.
- The free plan holds one product; a second one answers `402` with the plan to upgrade to.
- Tasks spend credits. The signup credits cover the first ones; the balance is in `orkosi_whoami` and in the hub under **Billing**.
- Archiving needs the owner of the product, which the signup key is. A key made for a team member follows that member's role.
- You keep the normal hub: sign in at [orkosi.com/login](https://support.orkosi.com/login) after setting your password, and everything the agent created is there.