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

# MCP server

> Connect Claude, ChatGPT, Cursor and other AI assistants to Just Flow It by signing in with your account, then organize projects and create, edit, view and export BPMN diagrams from the chat.

Just Flow It runs a remote [Model Context Protocol](https://modelcontextprotocol.io) server. Connect your AI assistant to it and ask in plain language: "create a project for client Acme with this context", "draw our purchase approval process", "add a step for the finance review", "show me the diagram", "export it to BPMN".

The assistant works on your real Just Flow It account, with the same rules as the REST API.

> [!NOTE]
>
> The MCP server needs a **Pro** plan, or a **Team** plan for the organization's owner (members can't connect the organization). You connect by signing in with your Just Flow It account, so there is no API key to create.

## Server URL

```
https://justflow.it/api/mcp
```

## Connect your assistant

Add the server URL to your assistant. The first time it connects, a browser window opens: sign in to Just Flow It and allow the app to access your diagrams. On that screen you choose where the assistant works: your personal account or an organization you own.

**Claude**

Works in claude.ai and in Claude Desktop.

1. Open **Settings → Connectors**.
2. Click **Add custom connector**.
3. Paste `https://justflow.it/api/mcp` and confirm.
4. Click **Connect**, sign in to Just Flow It and allow access.

**ChatGPT**

1. Open **Settings → Apps & Connectors**.
2. Create a connector and paste `https://justflow.it/api/mcp` as the server URL.
3. Sign in to Just Flow It and allow access.

If the option to create a connector isn't there, turn on developer mode in the advanced settings. Availability depends on your ChatGPT plan, and some plans may limit what a custom connector can change (for example, only Business, Enterprise or Edu workspaces may allow full write actions).

**Claude Code**

```bash theme={null}
claude mcp add --transport http justflowit https://justflow.it/api/mcp
```

Then run `/mcp` inside Claude Code, pick **justflowit** and sign in.

**Cursor**

Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json theme={null}
{
  "mcpServers": {
    "justflowit": {
      "url": "https://justflow.it/api/mcp"
    }
  }
}
```

Or open **Settings → MCP** in Cursor, add a server with the URL, and click **Login** when it shows up.

**Other clients**

Any client that supports remote MCP servers over Streamable HTTP with OAuth sign-in works. Point it at the server URL and sign in when it asks.

To disconnect an assistant, open **Settings → AI connections** in Just Flow It and click **Disconnect**.

> **For developers**
>
> Transport: Streamable HTTP (stateless, `POST` only). Clients must send `Accept: application/json, text/event-stream`, which every MCP client does. Authentication: OAuth sign-in with your Just Flow It account. JSON-RPC batches are not supported; send one message per request.

> **Connecting with an API key instead**
>
> Scripts and clients without sign-in can still send an API key in the `Authorization: Bearer <your API key>` header, along with `Accept: application/json, text/event-stream`. Create one in **Settings → API keys**. A key gives access to your diagrams, so keep it out of shared files and repositories. A key with fewer scopes limits what the assistant can do: the server only offers the tools the key's scopes allow.

## Tools

| Tool | What it does | Scope |
| - | - | - |
| `list_folders` | Lists your projects and folders | `folders:read` |
| `create_folder` | Creates a project or a folder, with optional AI context | `folders:write` |
| `update_folder` | Renames, changes the context of, or moves a project or folder | `folders:write` |
| `list_diagrams` | Lists diagrams, optionally in one folder | `diagrams:read` |
| `get_diagram` | Gets a diagram's details | `diagrams:read` |
| `get_diagram_image` | Shows the diagram as an image, drawn as in the editor | `diagrams:read` |
| `export_bpmn` | Exports standard BPMN 2.0 XML | `diagrams:read` |
| `import_bpmn` | Creates a diagram from BPMN 2.0 XML | `diagrams:write` |
| `update_diagram` | Renames a diagram or moves it to another folder | `diagrams:write` |
| `delete_diagram` | Deletes a diagram | `diagrams:write` |
| `generate_diagram` | Creates a diagram from a description of the process | `generate` |
| `edit_diagram` | Changes a diagram from an instruction | `generate` |
| `get_generation` | Checks a generation that is still running | `generate` |

Projects and folders can carry a **context** (who the client is, rules of the business). When the assistant generates or edits a diagram inside them, the AI uses that context.

## How generation works

Prompts can be up to 20,000 characters.

### Files

`generate_diagram` and `edit_diagram` take the same [attachments](https://docs.justflow.it/api-reference/generate.md#attachments) as the REST API: up to 4 images and 4 documents.

* **Text files** (`.md`, `.csv`, `.json`, `.bpmn`, `.txt` and the other [text types](https://docs.justflow.it/api-reference/generate.md#attachments)): the assistant passes the file's own text (up to 100,000 characters), not a summary. Works from assistants that can see the file's text, including the Claude and ChatGPT apps for files of normal size.
* **Images and PDFs** go as bytes, which the assistant has to write into the tool call itself. In practice that only works for very small files read from disk (Claude Code, Cursor). In the Claude and ChatGPT apps, the assistant describes the image or PDF in the prompt instead.

Creating or editing a diagram with AI usually takes 30 to 90 seconds. `generate_diagram` and `edit_diagram` wait up to 45 seconds (set `wait_seconds` to change it); if the diagram isn't ready yet, they return the generation id and the assistant checks it with `get_generation`. Most assistants do this on their own.

## Limits

The MCP server follows the same [rate limits](https://docs.justflow.it/api-reference/rate-limits.md) as the REST API. They are tracked per account (personal or organization) and shared by all of its API keys and connected assistants:

* Every tool call counts as one request to the matching endpoint (120 per minute).
* `generate_diagram` and `edit_diagram` share the monthly quota of 500 generations per rolling 30 days. While they wait, each status check also counts as one request.
* When a limit is hit, the tool error says when to retry.

## Troubleshooting

> **It asks for a Pro plan**
>
> Connecting AI assistants is part of the Pro and Team plans. If you're on Free or your plan ended, upgrade at [justflow.it/pricing](https://justflow.it/pricing), then go back to the sign-in tab and refresh the page.

> **My organization doesn't appear**
>
> Only the organization's owner can connect it. If you're a member, ask the owner to connect it, or connect your personal account.

> **I disconnected an assistant by mistake**
>
> Connect it again from the assistant. You sign in once more and it's back.

> **I signed in with the wrong account**
>
> Click **Switch account** on the consent screen and sign in with the right one.

> **I can't connect another assistant**
>
> Each account can have up to 20 connected assistants. Disconnect one you no longer use in **Settings → AI connections** and try again.


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