Docs / Build
AI assistants (MCP)
Connect Claude, ChatGPT, Cursor or any MCP client to your workspace so it can read your projects, build flows and blocks, run them on your workers and read the results.
What it does
EsaSim is an MCP server (Model Context Protocol). An AI assistant connected to it works in one of your workspaces, as you: it can look at your projects, flows, blocks, runs, logs, results and datasets, build or change flows, make blocks of its own in Python or JavaScript, start runs on your workers and follow them. It never does more than you could in the dashboard: your role in the workspace and in each project still applies.
The server address is https://<your EsaSim address>/mcp; Account > AI assistants shows it.
Connect an assistant
Claude, ChatGPT and other apps (sign in)
- In the app, add a custom connector (in Claude: Settings > Connectors > Add custom connector) with the server address.
- The app opens EsaSim. Sign in if asked, choose the workspace and what the assistant may do, and choose Allow.
- Back in the app, ask for something: "List my EsaSim projects", "Build a flow that reads the dataset Landing frames, asks an agent to find frames without a landing pad, and keeps them as a new dataset".
The connection uses OAuth 2.1 with PKCE; the app registers itself the first time. Its access lasts an hour and renews itself; remove it any time under Account > AI assistants > Connected apps.
What it may do is fixed when you choose Allow. An assistant connected with Read can look but cannot create projects, change flows or run them, and says so when asked. To give it more, remove it under Account > AI assistants > Connected apps, add it again in the app, and choose Build or Build and run. Account > AI assistants shows the access of each connected app.
ChatGPT
ChatGPT calls tools that change things (create a project, change a flow, run it) only in Developer mode; without it, a connector can only read.
- In ChatGPT on the web: Settings > Apps > Advanced settings, turn on Developer mode. It is offered on Plus, Pro, Business, Enterprise and Education accounts; in a Business or Enterprise workspace an admin may have to allow it.
- Create app: give it a name (EsaSim), the server address, and OAuth as authentication.
- ChatGPT opens EsaSim: choose the workspace and Build or Build and run, then Allow.
- In a chat, turn the app on (the + menu, Developer mode) and ask. ChatGPT asks you to confirm each change before it makes it; you can let it remember your answer for the conversation.
ChatGPT reads the list of tools when it connects. After you change the access, reconnect the app (or use its Refresh) so it sees the new tools. If ChatGPT says a call was blocked by safety checks, the call never reached EsaSim: try again, or start a new chat.
Claude Code, Cursor and scripts (token)
- Under Account > AI assistants, make a token: a name, the access, and an expiry. It works in the workspace open at that moment. Copy it: it is shown once.
- Give it to the client as a header. With Claude Code:
claude mcp add --transport http esasim https://<your EsaSim address>/mcp \ --header "Authorization: Bearer esa_…"
Tokens start with esa_ and are stored as a hash. Remove one and it stops working at once.
Access levels
| Access | The assistant may |
|---|---|
| Read | See projects, flows, blocks, workers, runs, logs, result files and datasets. |
| Build | Also create projects, create and change flows (the draft, as in the editor), make and change the workspace's blocks, and publish flows. |
| Build and run | Also start and stop runs on the project's workers. Runs use your workers, and EsaSim Cloud credits when a project uses the cloud. |
Changing a flow needs the editor role in its project; running needs runner. Secret settings (API keys) cannot be set by an assistant: paste them in the editor. Every change and run an assistant makes is in the workspace's audit log, with the name of the token or app.
Tools
| Tool | What it does |
|---|---|
get_started | A guide for the assistant: concepts, port types, the graph format, the code API of blocks. |
list_projects, list_flows, get_flow | Projects and their flows (and the project templates); a flow's graph with its problems and the checks of the workers that would run it. |
create_project | A new project, empty or from a project template with its flows. It is saved to a GitHub repository of yours as it is made, so your GitHub account must be linked (Profile > GitHub). |
list_blocks, get_block | The blocks of the workspace (built-in, EsaSim library, your own) with ports, formats and settings; one block's code. |
list_workers | The project's workers, their accelerators and whether they can run blocks now. |
list_runs, get_run, get_run_log | Runs, each block's tasks and errors, and the log. |
get_run_results, get_result_file | Every file a run made, with the datasets it read, a download link for each file and one for a zip of all of them (links work for an hour without signing in); a file's text, a picture the assistant can see, or any file as base64 up to 8 MB. Files left on a worker are fetched from it first. |
list_datasets, list_dataset_files | Datasets and their files. |
create_flow, update_flow, publish_flow, delete_flow | Make a flow (empty or from a template), replace its graph (blocks without a position are placed automatically), publish a version, delete a flow that is no longer useful (its exact name confirms it; its runs and results are kept; project admins and whoever created the flow). |
save_block | Create a block or a new version of one: definition and code. EsaSim writes the header of its code. Platform admins can also change EsaSim's own and library blocks (below). |
upload_file | Put a file into a project: into one of its datasets (made for the project on the first upload when you name a new one), as text or as base64 for any other file (a trained model, a picture, a zip); a large file in parts. Each upload makes a new version of the dataset, or several files together make one. Files for a computer's folder are written by its worker. Needs Build access and the editor role in the project. |
list_assets, project_assets | A project's assets (the files its views draw with: 3D models, textures, sounds): list them, put or replace one (text or base64, up to 8 MB), delete one, or take the 3D view's own copies the project uses into its assets. |
run_flow, stop_run | Start a run (the draft is published first if it changed) or stop one. |
Changes an assistant makes to a flow appear in the editor; reload the flow if you have it open. The editor's console shows the problems and the log of its runs like any other.
Platform admins: EsaSim's own blocks
EsaSim's own blocks (built in) and the blocks of the EsaSim library are used by every workspace, so only EsaSim's platform admins can change them. An assistant connected by a platform admin, with Build access or more, can:
- Change a platform block with
save_blockand itsblock_id(such asviewer-3dor anx-…library block): only the fields it passes change, ordefinitionreplaces the whole definition (get_blockreturns it); the code is kept when left out. The new version is in force at once in every workspace. - Add a block to the EsaSim library with
save_blockandlibrary: true. - See and undo changes with
platform_blocks:list,history,revertto an earlier version,use_releaseto put one of EsaSim's own blocks back to the release's version,unpublishandrepublishfor library blocks.
A change to one of EsaSim's own blocks is kept by EsaSim, not in the release's files, and is numbered after the release's version: 1.76+1, 1.76+2… Installing a new release does not remove it. When the release brings a newer version of a block that has a change, get_block says so and gives the release's definition and code to merge; Admin › Shared blocks lists the changed blocks with a button to go back to the release's version. Every change is in the platform's audit log.
Review public projects with review_public_projects (platform admins): a project asking to be public waits for a platform admin before it shows under Projects › Public. list gives the requests; read gives everything to check of one project (its readme, blueprints and the code of its blocks as text, its files listed, and signals worth a look: outside addresses, risky calls, secrets, executables); file reads one of its files; approve makes it public; reject keeps it private with a note its people read. The same requests are under Admin › Public projects.
For everyone else, EsaSim's own blocks and library blocks are read-only: save_block refuses them and suggests saving a workspace block from their code, and platform_blocks is not offered.
Good to know
- The server answers JSON over HTTP POST (MCP Streamable HTTP, protocol versions 2024-11-05 to 2025-06-18). It needs no session and opens no event stream.
- At most 600 requests per token in 10 minutes, and 60 runs per person per hour.
- One connection reaches one workspace. For another workspace, connect again and choose it.
- Table settings, such as the objects of a 3D scene block, are lists of rows;
list_blocksgives their columns.