# Uniwork — set up

Uniwork is one platform that replaces the SaaS stack a business rents. It ships
43 ready-made apps — CRM, invoices, projects, HR, help desk, docs, forms,
roadmap, campaigns, commerce and more — on one data model, plus automations and
673 connectors to the outside tools they keep.

Those 43 are a starting point, not a catalogue. Over MCP you can install any of
them, install a whole starter pack for a kind of business, or create a new app
in the workspace and hand App Studio the brief when nothing fits. Installed apps
declare what they may read from each other, so you are working with a connected
business rather than gluing one together.

Every one of those apps is also an MCP server, and the platform itself exposes
its management surface over MCP. So you can do the work headlessly — the web UI
at `https://app.uniwork.ai` is the same platform with screens on it, for the
people who prefer clicking.

- API base: `https://api.uniwork.ai`
- Protocol: MCP, JSON-RPC 2.0 over Streamable HTTP (`POST`; `GET` returns 405 —
  there is no server-initiated streaming)
- Credential: a personal access token, `uat_…`, valid 90 days

## 1. Check what is there — no token needed

`initialize`, `tools/list` and `ping` answer unauthenticated, so you can look
before anyone signs in:

```sh
curl -s https://api.uniwork.ai/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

`tools/call` needs a token, and runs as the human who approved it — their
permissions, their audit log, nothing more.

## 2. Get your own token

If the human already has one (Settings → Security → CLI tokens), ask for it and
skip to step 3. Otherwise run the device flow yourself — three calls:

```sh
# a) start. `label` is shown to the human on the consent screen; name yourself.
curl -s https://api.uniwork.ai/api/v1/auth/cli/start \
  -H 'content-type: application/json' \
  -d '{"label":"Claude Code"}'
# => { "device_code": "...", "user_code": "ABCD-1234",
#      "verification_uri": "https://app.uniwork.ai/cli-auth",
#      "verification_uri_complete": "https://app.uniwork.ai/cli-auth?code=ABCD-1234",
#      "interval": 5, "expires_in": 600 }
```

b) Print `verification_uri_complete` and the `user_code` and ask the human to
open it and approve. They must be signed in to Uniwork; the code expires in ten
minutes.

```sh
# c) poll, no faster than `interval` seconds — polling harder returns
#    rate_limited / "slow_down".
curl -s https://api.uniwork.ai/api/v1/auth/cli/token \
  -H 'content-type: application/json' \
  -d '{"device_code":"<device_code>"}'
# => {"status":"pending"}                        keep polling
# => {"status":"approved","access_token":"uat_…","token_type":"bearer"}
# => {"status":"denied"} | {"status":"expired"}  stop, tell the human
```

The token is handed back **once** — store it before you do anything else, and
never print it. Put it in the environment as `UNIWORK_TOKEN`.

## 3. Add the server

Claude Code:

```sh
claude mcp add --transport http uniwork https://api.uniwork.ai/mcp \
  --header "Authorization: Bearer $UNIWORK_TOKEN"
```

Cursor (`~/.cursor/mcp.json`) or Claude Desktop, inside `mcpServers`:

```json
"uniwork": {
  "url": "https://api.uniwork.ai/mcp",
  "headers": { "Authorization": "Bearer ${UNIWORK_TOKEN}" }
}
```

Any client that can send an `Authorization` header works. Hosted connectors on
claude.ai and ChatGPT do not yet — they sign in with OAuth, which Uniwork does
not serve.

## 4. Pick the surface

`/mcp` carries everything. The three narrower URLs exist so a client that only
needs one job does not load 64 tool definitions:

| Endpoint | Tools | What it does |
|---|---|---|
| `https://api.uniwork.ai/mcp/platform` | 18 | organizations, workspaces, members, plans, usage |
| `https://api.uniwork.ai/mcp/studio` | 24 | browse the store, install apps and packs, create a new app, move apps between workspaces |
| `https://api.uniwork.ai/mcp/automations` | 22 | build, deploy, run and approve automations; connectors and connections |
| `https://api.uniwork.ai/mcp` | 64 | all three on one URL |

## 5. The apps are servers too

Each installed app serves its own tools, derived from its OpenAPI spec — 2,400+
across the suite, e.g. 117 on Campaigns, 111 on Projects, 104 on Commerce.

- Endpoints: `POST <app-url>/mcp` (JSON-RPC) and `GET <app-url>/mcp-tools`
- Credential: a `umcp_` token, minted in the app's MCP pane in the UI
- A `umcp_` token is **read-only, always**, and carries a per-token allow-list —
  `tools/list` is filtered to it and a `tools/call` outside it is refused at the
  edge. Ask for the tools you need by name.

## Rules

- Act as the human, not around them. If a call is refused, it is their
  permissions; say so instead of hunting for another route.
- Nothing here grants write access to another app's data. Cross-app writes go
  through the platform's own tools on `/mcp/studio`.
- The web UI and these tools are one system. A record you create over MCP is
  the record their team sees on screen a second later.