Machinations

Machinations MCP: connect Claude, ChatGPT and Cursor

4 min read

Machinations MCP lets an AI assistant work in Machinations for you. Claude, ChatGPT, Cursor and other tools that speak the Model Context Protocol (MCP) can open your diagrams, build new models, change values and Play them, then read the results back to you. You keep a model you can see, check and correct in Machinations.

The server address

Every AI tool connects to the same address:

https://my.machinations.io/mcp

You add it once. The first time your AI connects, it opens a Machinations page where you sign in (or create a free account) and approve what the AI may do. You can untick any permission you don't want to give.

Add it to Claude

  1. In Claude (on the web or in the desktop app), open Settings, then Connectors.
  2. Choose Add custom connector, name it Machinations and paste https://my.machinations.io/mcp.
  3. Choose Connect, then approve access on the Machinations page that opens.

In a chat, ask for what you want, for example: “Use Machinations to build a model of my game's economy and Play it.”

Add it to ChatGPT

  1. In ChatGPT, open Settings, then Apps & Connectors, and turn on Developer mode under the advanced settings.
  2. Create a connector, name it Machinations and paste https://my.machinations.io/mcp as its address, with OAuth as the sign-in.
  3. Approve access on the Machinations page that opens, then pick Machinations in a chat's tools.

Custom connectors need a paid ChatGPT plan, and in a Business, Enterprise or Edu workspace an admin may have to allow them. OpenAI moves these settings from time to time: if you don't see Developer mode, look under Settings, then Security.

Add it to Claude Code

Run this once in a terminal, or ask Claude Code to run it for you:

claude mcp add --transport http machinations https://my.machinations.io/mcp

Start a new Claude Code session, run /mcp and choose Machinations to sign in and approve access.

Add it to Cursor or VS Code

Add Machinations to the editor's MCP settings file (.cursor/mcp.json in Cursor, .vscode/mcp.json in VS Code), then approve access when the editor asks:

{
  "mcpServers": {
    "machinations": { "url": "https://my.machinations.io/mcp" }
  }
}

VS Code names the top key servers instead of mcpServers and adds "type": "http" to the entry. A tool that cannot sign in with a browser can use a personal access token instead: create one in Machinations under Settings, API key, in the AI agents (MCP) box.

What your AI can do

  • List your diagrams. It sees the diagrams in your account, with their names and links.
  • Open or show a diagram. It reads a diagram's nodes, connections and values. In Claude and ChatGPT it can also show the diagram right in the chat, where you can Play it.
  • Create a diagram. It writes a model in Machinations' modeling language, checks it and saves it as a new diagram.
  • Edit a diagram. It changes values in a diagram and saves them as a new version, so you can always go back.
  • Play a diagram. It Plays the model many times and reads the results, for example what an Outcome ends at after 100 steps.
  • Check your Credits. It reads how many Credits you have left this month.

Plans and Credits

  • MCP is included on every plan.
  • Plays your AI starts spend Credits the same way Plays in the app do. A Play starts only while your monthly Credits cover it; Top-up Credits are not used. See Machinations Credits.
  • Each plan has daily limits on how many diagrams your AI can create and edit and how many Plays it can start. Paid plans allow more steps per Play and larger models.
  • On the Community plan, diagrams your AI creates are public, as diagrams you create yourself are, and your email address must be verified before your AI can create, edit or Play. Paid plans create private diagrams.

Remove access

In Machinations, open Settings, choose API key and find the AI agents (MCP) box. It is there on every plan. Connected apps lists every AI tool you approved: choose Disconnect to remove one. Personal access tokens lists the tokens you created, and you can revoke any of them there.