Connect your AI app

You can ask the AI in Claude Code, Claude Desktop, claude.ai, ChatGPT, VS Code or another app that supports MCP to work on your diagrams. You add Penna as a connector once, sign in with your Penna account, and the AI can then list, open, create and edit your diagrams while you watch them change in the app.

The connector URL is:

https://app.penna.studio/mcp

The app shows these steps, with a copy button, in Settings > Use with your AI app.

Add the connectorCopy Anchor Link

Any other app that supports MCP connectors with sign-in (OAuth) can use the same URL.

Sign in and allow accessCopy Anchor Link

When you connect, your AI app opens Penna's own sign-in page in your browser. It's the same page you use for the app, so sign in the way you usually do: Continue with Google, or your email and password. If you're already signed in to the app in that browser, this step is skipped.

The workspace is invite-only, so only emails the admin has invited get in. Connecting an AI app doesn't change that.

Next comes a consent page that asks whether to let the app use your diagrams. It says the app will be able to list, read, create and change the diagrams in your account, and shows:

• the email you're signed in as,
• where the access goes,
• who published the app. Apps that publish their own details show a verified domain. Apps that register on the spot show a note that the name they gave isn't verified.

When the app runs on your computer, as Claude Code does, the page adds a warning: allow it only if you asked it to connect a moment ago. Choose Allow to finish, or Cancel to stop. Your AI app is then connected, and the app may skip this page the next time you connect the same app.

Ask it to work on your diagramsCopy Anchor Link

Once connected, you can ask for things like "draft an employee onboarding process in Penna" or "add a credit check before approval in the loan diagram". See What to ask for more. The AI can:

• List your diagrams, including which one is open in the app. When you say "this diagram", it takes that to mean the open one.
• Open a diagram in the app, so you can watch while the AI works.
• Create a diagram, a BPMN process or a sequence diagram, which also opens it in the app.
• Read and edit a diagram, either by rewriting it in Flowmark, or sequence code for a sequence diagram, or with small edits that keep everything else as it was.
• Look up guidance: the Flowmark syntax, modeling style, common patterns and reference processes for many business domains, and the sequence code syntax, drawing style and reference interactions for sequence diagrams.

Any tab of the app you have open updates live as the AI works. The status bar says "Your AI app is editing the diagram" while it does. The assistant panel lists each change under Your AI app, one line each, and every change is saved to the diagram's version history, so you can go back to an earlier version.

When the AI creates, opens, reads or changes a diagram, the result ends with a link to that diagram in the app, so you can open it from the chat in one click.

Every tool that reads or changes a diagram names it by its id (diagram_id). Switching to another diagram in the app while the AI works never redirects its changes: they still go to the diagram it was working on. If you and the AI change the same diagram at the same moment, its change is refused, and it's told to read the diagram again and retry.

After each change the AI gets the same modeling checks you see in the app, and it's told to fix the errors before it finishes. When a fix depends on what you meant, such as a step connected to nothing, it's told to ask you first.

See the diagram in the chatCopy Anchor Link

In chats that can show interactive content from a connector (MCP Apps), such as claude.ai, Claude Desktop, ChatGPT and VS Code, the AI's changes come with a diagram card right in the conversation. You can also ask it to show you a diagram, and it draws one without changing anything. The card shows:

• the diagram's name and what the change did, such as "Added Check budget",
• the diagram itself, which you can pan and zoom, with the steps the AI just added or changed ringed for a moment,
• Changes, a list of what the AI added, changed and removed. Point at a row to find its element, or select it to keep it marked.
• Problems, the same modeling checks you see in the app, with the elements they're about marked on the diagram,
• Show latest version, which redraws the card if the diagram has changed since, in the app or by the AI,
• Full screen, where the chat allows it, and Open in Penna.

You can also act on the diagram from the card:

• Select a step, event or gateway by clicking it. The AI is told what you selected, so "make this a user task" works the way it does in the app's assistant.
• Ask about this opens a box over the selection. What you type goes into the chat as your message, about that step.
• Rename and Delete change the step right away. Deleting a step joins the steps before and after it, as on the canvas.
• Undo in the card's header takes back the change the AI made in that card, putting the diagram back to the version before it.

Each of these is saved to the diagram's version history, shows up live in any tab of the app you have open, and the AI hears about it before its next change. If the diagram has changed since the card was drawn, the card refuses and asks you to show the latest version first, so it never changes something you haven't seen. In a sequence diagram you can select, rename and delete participants, messages, notes and fragments the same way.

Export in the card's header downloads the diagram, where the chat allows downloads: a BPMN 2.0 file (.bpmn) that opens in Penna and in other BPMN tools, or an SVG image. Sequence diagrams export as Mermaid or PlantUML text instead of a BPMN file. Images always come out in the light theme, as they do from the app.

The card reads and edits your diagrams through the same connection as the AI, so it reaches only diagrams your account can open. Some chats ask you to allow each of the card's actions the first time. In chats that don't show cards, you get the link instead, and nothing else changes.

Disconnect an appCopy Anchor Link

Settings > Use with your AI app has a Connected apps list with every app you've allowed and when you connected it. Choose Disconnect next to an app to take its access away at once. You can connect it again later by repeating the steps above.

Removing the connector inside your AI app doesn't remove it from this list, so disconnect it here too.

Fix connection problemsCopy Anchor Link

"Too many apps registered today. Try connecting again tomorrow." Some apps register themselves with the server the first time they connect. The server accepts 50 of these a day across everyone, so nobody can use up its storage. Try again the next day (days are counted in UTC), or ask the admin to raise the limit.

You can't get past the sign-in page. Only invited emails can sign in. With a password, an email that isn't invited gets "That email and password don't match." With Google, the page says your email isn't on the invite list. Ask the workspace admin to invite the email you're signing in with. After ten wrong passwords in a row, the account is locked for 15 minutes.

"This connection request didn't work." The request from your AI app was incomplete or had expired, or the app's details couldn't be checked. Start connecting again from your AI app.

"You were signed out." Your app session ended while the consent page was open. Sign in to Penna, then start connecting again from your AI app.

Your AI app stops being able to reach your diagrams. A connection lasts 30 days from the day you allowed it. Within that time your AI app renews its access every hour without asking you. After 30 days, or after you choose Disconnect, sign in again: in Claude Code run /mcp, in Claude Desktop or claude.ai connect the connector again under Settings > Connectors, and in other apps connect it again where you added it.

"This account no longer has access to Penna." The admin removed you from the workspace, which also disconnects your AI app. Your diagrams stay saved, and if the admin invites you again you can reconnect.

What the AI is toldCopy Anchor Link

Your AI app gets a short set of instructions when it connects, a list of tools, and guidance it can look up. Some apps shorten or ignore a server's instructions, so the tools carry what the AI needs: the tool that writes a diagram includes a summary of Flowmark, and the full syntax is one lookup away. The tools that create and change a diagram ask the AI to call read_context first, for your team's business context and learnings.