# Connect a chat app

> Connect an AI chat app to Artor so it can publish prototypes and create public links for you.
> URL: https://artor.app/docs/connect-a-chat-app

**Warning:** 
  The connector is in **beta**, and connecting isn't open to every account yet. If Artor says
  "Connecting AI apps to Artor is not open yet.", your account isn't in the beta.

Artor has a remote MCP connector. Once you connect a chat app that supports custom MCP
connectors (ChatGPT in developer mode, the Anthropic chat apps, and others Artor approves), the
app can, on your behalf (Artor's own screens call these **AI apps**):

- see where you can publish: your organizations, Spaces, and folders;
- list and search the prototypes you can open, and read a version's source;
- publish a new static version, from HTML or markdown it wrote in the chat;
- create a [public link](https://artor.app/docs/sharing) to a prototype.

Every call acts as **you**, only in the organizations you ticked when you connected, and goes
through the same checks as the CLI and the dashboard. The app can't do anything you couldn't do
yourself.

## Connecting

The connector address is:

```text
https://dash.artor.app/mcp
```

**Note:** 
  Running your own instance? Use your Artor address followed by `/mcp`. An operator approves each
  chat app first, in the backoffice under **Connector clients**; until then the app is sent to the
  "isn't supported" page.

### ChatGPT

1. Turn on **developer mode** in ChatGPT's settings. ChatGPT moves this setting from time to
   time, and on a workspace plan an admin may have to allow it first; OpenAI's
   [developer mode guide](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-connectors-in-chatgpt)
   has the current steps.
2. Create a custom app (connector) with the address above and OAuth as the authentication.
3. Approve the connection on Artor's consent page (below).

### The Anthropic chat apps

1. Open **Customize > Connectors**, choose **Add**, then **Custom** and **Web**.
2. Enter the address above.
3. Approve the connection on Artor's consent page (below).

Only chat apps Artor has approved can connect. Any other app is sent to a page saying it isn't
supported.

### The consent page

Artor shows its own consent page every time you connect. It names the app, the site it comes
from (**From**), whether it **Runs on this computer** (a desktop app), where it **Sends you back
to** when that's a different site, how long the connection lasts, and the account you're signed in
as. Check that account on a shared computer; **Switch account** signs you out and brings you back
to the same page after you sign in again.

- **Permissions.** Each permission the app asks for starts ticked; untick one you don't want to
  give:
  - **Prototypes:** list where you can publish, list and read prototypes, and publish versions.
  - **Public links:** create public links. Untick it if the app must never open a prototype to
    people outside your organization.
- **Organizations.** Tick each organization the app may use. It can't see or act in any other.
  If the page lists only one organization, it's already ticked.

**Enable all** (Permissions) and **Select all** (Organizations) tick or untick a whole box at once.

Click **Allow** to connect, or **Cancel** to send the chat app away with nothing connected.

At least one organization and one permission have to stay ticked. If you untick every
organization or every permission, Artor ends the request with a message saying why; connect
again from the chat app. You need to belong to at least one organization to connect, and after
30 attempts in 10 minutes Artor asks you to wait before connecting again.

With only **Public links** allowed, the app can't look prototypes up, so it can only create a
link for a prototype whose ID you give it. The ID is the last part of the prototype's dashboard
address, `/p/{id}`.

If you aren't signed in, Artor's login opens first and the consent page follows. Creating a new
account with a password doesn't carry the request through; connect again from the chat app once
you're signed in. The consent page expires after **10 minutes**; if it does, connect again.

**Note:** 
  Each time you approve, Artor creates a new connection. Reconnecting the same app adds another
  entry in **Settings > Connected apps**; revoke the one you no longer use.

## Managing connections

**Settings > Connected apps** lists your live connections: the app's name and address, the
organizations it covers, and when it last signed in or renewed its sign-in.

- **Revoke** ends the connection. The app has to connect again, and you approve it again.
- **Remove an organization** takes one organization off a connection and keeps the others.
  Removing the last one ends the connection, and Artor asks you to confirm that first.
- To **add** an organization, connect again from the chat app and tick it.

Leaving an organization, or being removed from it, takes it off your connections automatically.
If you rejoin, connect again to give the app access to it. A connection whose organizations you
have all left shows **No organizations** and can't do anything; revoke it or let it expire.

While your account is suspended, every call is refused. If the app tries to renew its sign-in
during the suspension, the connection ends; connect again once the suspension ends.

### How long a connection lasts

The app gets a sign-in that lasts **one hour** and, if it asked to stay connected, a renewal
that lasts **30 days** and is replaced, for another 30 days, every time the app renews its
sign-in. So a connection the app renews at least once every 30 days keeps working. One not renewed
for 30 days, or one that never asked to stay connected (it lasts the hour), ends; connect again
from the chat app.

## What the app can do

The app picks these tools itself from what you ask in the chat. You don't call them by name,
but knowing them helps you ask for the right thing.

| Tool | Permission | What it does |
| --- | --- | --- |
| `list_destinations` | Prototypes | Your account, your organizations on this connection, and for one organization: its plan, whether you can publish, and the Spaces and folders you can write to. |
| `list_prototypes` | Prototypes | Prototypes you can open in one organization, newest first, 25 at a time. Can filter by part of the name or by folder. |
| `get_source` | Prototypes | The source of one version (the latest by default), up to 500 files a page. Can narrow to some files or folders. |
| `publish` | Prototypes | Publishes a new static version: either a new prototype, or a new version of an existing one. |
| `create_share_link` | Public links | Creates a public link to a prototype. |

If you hold a [reviewer seat](https://artor.app/docs/seats), the app can list prototypes and create links (with
**Public links** allowed), but it can't read source or publish.

Very large files, and binary files other than images, come back from `get_source` without their
content. For the complete source, use [`artor pull`](https://artor.app/docs/deployments#get-the-source-back).

Names, notes, and source the app reads back from Artor are your team's content. Artor tells
the app to treat them as content, never as instructions.

### Publishing

The app either creates a **new prototype** (it gives a name) or adds a **new version** to an
existing one (it gives the prototype's ID, which it can find with `list_prototypes`).

- **A new prototype** goes into the folder the app picks, or into the organization's **Draft**
  folder. If the connection covers more than one organization, the app has to say which one;
  it gets the list and should ask you. You can name the organization as it appears in Artor,
  in any capitalization: the app can pass its name, its slug or its id. If two of your
  organizations share that name, Artor asks which one rather than guessing. The new
  prototype's name follows the
  [prototype name rules](https://artor.app/docs/cli#prototype-names).
- **A new version** goes into the prototype's own organization. The app doesn't need to name
  the organization, since Artor finds it from the prototype.
- **Every publish is a new version,** even with identical content. Versions are never
  overwritten, and `latest` moves to the new one (it always points at the highest live version
  that isn't turned off). A short note can go with it as the version's
  [changelog](https://artor.app/docs/cli#changelog) line.
- The result includes the **version link**, which always opens that exact version. It opens
  only for members who can open its Space; to share it outside, ask the app for a public link.

Publishing uses the same seat, Space permissions, storage, and publishing limits as
`artor publish`.

#### When the name is already taken

Before creating a prototype, Artor checks whether one you can see already has that name
(ignoring letter case and extra spaces). If so, nothing is published: the app gets up to 10
matching prototypes and should ask you whether to publish a new version of one of them or pick
another name. The check includes prototypes in Spaces you can only read; you can't publish into
those, so pick another name or ask for write access. Prototypes in the trash don't count.

### Content the app can publish

The app sends one of four kinds of content:

| Kind | What gets published |
| --- | --- |
| HTML | One page, published as `index.html`. |
| Files | A set of files that must include `index.html` at the top. |
| Markdown | One markdown document, shown through Artor's [markdown viewer](https://artor.app/docs/preview#markdown-versions). |
| Markdown with images | The document plus images (PNG, JPEG, GIF, WebP, AVIF; no SVG), shown through the markdown viewer. |

Rules a publish can run into:

- **File names** use plain printable ASCII. Each folder or file name can be up to **255
  characters**, and a whole path a little under 1,000.
- **Names that don't work on Windows are refused,** so the published files can be pulled onto
  any computer: names containing `\ < > : " | ? *`, names ending in a space or a dot, and
  reserved device names such as `CON`, `PRN`, `AUX`, `NUL`, `COM1` or `LPT1`, with or without an
  extension.
- **Two paths that differ only in letter case,** or a file with the same name as a folder, are
  refused.
- **Secret files are refused,** never silently dropped: `.env` files, `.npmrc`, keys,
  `node_modules`, `.git`, and the other files the CLI also keeps out of a publish.
- **Limits:** at most **10,000 files**, a markdown document at most **1 MB**, the whole publish
  within your plan's [static build size](https://artor.app/docs/plans), and one request at most **4 MiB**. The
  request size is usually the one you reach first; publish larger sites with the
  [CLI](https://artor.app/docs/publish-a-prototype).

### Creating a public link

The app creates a link to a prototype's latest version, or pins it to one version. It follows
the same rules as a link from the dashboard: [duration limits](https://artor.app/docs/sharing#duration),
[who can share](https://artor.app/docs/sharing#who-can-share), and [passwords](https://artor.app/docs/sharing#password-protection).

- **Lifetime:** 7 days unless the app asks for another length.
- **Comments** follow your organization's
  [default for new links](https://artor.app/docs/sharing#setting-the-default-for-new-links).
- **Password:** the app can set one you give it or have Artor generate one. If your
  organization requires a password and the app asks for neither, no link is created and the
  app is told why.
- **A generated password is shown once,** in the chat. Artor can't show it again, so copy it
  from the chat.
- Turning the link off, extending it, and every other setting stay in the dashboard and the
  [CLI](https://artor.app/docs/sharing#from-the-cli).

**Warning:** 
  The link and its password pass through the chat, so the chat provider stores them with the
  conversation. Anyone with access to that conversation can open the link.

## What's recorded

Connecting an app, revoking it, removing an organization from it, and every public link it
creates appear in each organization's [audit log](https://artor.app/docs/audit-log). Publishes aren't in the
audit log, like CLI publishes.

## Errors the app may report

The app gets a short reason with each refusal and usually explains it to you. The most common
ones you can act on:

| Code | What it means |
| --- | --- |
| `not_found` | The organization, prototype, folder, or version doesn't exist, isn't on this connection, or is in a Space you can't open. |
| `insufficient_scope` | You didn't allow this when connecting (for example, **Public links** was unticked). Connect again and allow it. |
| `rate_limited` | More than 300 requests from this connection in a minute (every request counts, not just tool calls). The app gets a wait time and tries again after it. |
| `server_busy` | Artor is busy reading source for other requests. The app waits the time it's given and tries again. |
| `source_too_slow` | Reading the source took too long. Ask the app to read fewer files or folders at once. |
| `publisher_required` | Reading source or publishing needs a publisher seat. Ask an organization admin. |

Every other refusal comes with a reason that says what went wrong, such as a name that's
already taken, a Space you can only read, a prototype in the trash, or content that's too large.
The app either fixes it and tries again, or tells you what to do.

If Artor can't reach the chat app's provider to confirm the app, Artor refuses the app's calls
until the provider is back (this can start up to an hour into the outage). The app's renewal
isn't used up: an app that keeps it carries on once the outage ends, but many apps treat the
refusal as final and drop the connection. If yours does, connect again.

## Honest limits

- **A lost reply can mean a second version.** If the chat app doesn't get Artor's answer, it may
  publish again. The extra version is visible and you can [delete it](https://artor.app/docs/deployments#deleting-a-version).
- **A failure right after creating a prototype** can leave a new prototype with a failed
  version. The app is told its ID, so it can publish into it on the next try.
- **Names aren't reserved.** Two requests creating the same name at the same moment both create
  a prototype.
- **The app decides what to call.** What limits it are the permissions you ticked, your own
  access, your organization's limits and password rule, the audit log, and revoking in
  **Settings > Connected apps**.
- **A page's own security settings** can block the review widget, so reviewers can't comment on
  that page. If comments don't appear, ask the app to remove any content security policy from
  the HTML.

## Related

- [Public sharing](https://artor.app/docs/sharing): how public links work
- [Preview URLs](https://artor.app/docs/preview): version links and markdown versions
- [Seats](https://artor.app/docs/seats): who can publish
- [Audit log](https://artor.app/docs/audit-log): what's recorded