Skip to content

Connect an AI agent over MCP

Studio exposes your organization’s models to AI agents over the Model Context Protocol (MCP). An agent that is connected can read your projects, event models, brainstorming boards and concepts, and change them. Ask it to add a slice and it adds the slice, instead of describing how you would.

YOUR ORGANIZATION Projects Event models Brainstorming boards Concepts fixed by the credential client ID and secret token, valid for an hour bearer token reads changes TOKEN /.cratis/token AI AGENT Your MCP client MCP ENDPOINT /mcp
The credential decides the organization. An agent that can read the models can change them too.
  • Issuing or rotating the credential needs a maintainer of the organization. Anyone who can open Settings > MCP can read it, so keep that page to people you would trust with the agent’s access.
  • Each organization has one credential: a client ID and a client secret. The agent works inside that organization and cannot see another one.
  • An MCP-capable client: Claude Code, an editor’s assistant, or any program that can talk to an MCP server over HTTP and send a bearer token.
  1. Open Settings > MCP.
  2. Read the Endpoint and the Client ID. The client ID is your organization’s name, so it is not a secret.
  3. Next to Client secret, select Show to reveal the secret. Select Hide when you are done.
  4. If the page says the organization has no MCP credential yet, select Issue credential. If that fails, the organization’s encryption key may not be ready yet; try again in a moment.

Select How to connect for a dialog that fills these snippets with your own values.

The client secret is exchanged for a short-lived bearer token. The token is valid for an hour. The answer also carries a refresh token, which you can exchange for a new token without sending the secret again.

Terminal window
curl -X POST https://mcp.cratis.studio/.cratis/token \
-d grant_type=client_credentials \
-d client_id=<client-id> \
-d client_secret=<client-secret>

Use the endpoint address shown on the MCP settings page if it differs from the example.

Most MCP clients take a URL and a header. With Claude Code:

Terminal window
claude mcp add --transport http cratis-studio https://mcp.cratis.studio/mcp \
--header "Authorization: Bearer <access_token>"

For a client that reads its servers from a configuration file, the equivalent is:

{
"mcpServers": {
"cratis-studio": {
"type": "http",
"url": "https://mcp.cratis.studio/mcp",
"headers": { "Authorization": "Bearer <access_token>" }
}
}
}

The header name and the bearer scheme are the same in every client. If your client does not support custom headers, put a small proxy in front that adds the header.

Ask your agent to run studio_whoami. It should answer with your organization’s name. Then ask it to list your event models. If it can, the connection works.

The agent gets Studio’s tools. The ones you will use most:

  • Read the model. List and read event models and brainstorming boards, find an item by name, and read the structure of a project.
  • Change the model. Create event models and brainstorming boards, add and move events, regions, sticky notes and chats, set a sticky note’s color, and add concepts, constraints, state machines and workflows.
  • Edit an event model in Screenplay. Open a session on an event model, read and propose typed edits in Screenplay, and apply the accepted result to the board.
  • Read board findings. Get what the board’s checks report: compiler errors and the gaps in the model.
  • Export context. Hand a slice, a feature, an event model or a domain to a coding agent as Markdown, JSON, YAML or TOON. See Agent context.
  • Reach everything else. A catalog of every Studio command and query lets an agent do anything that has no named tool.

MCP tools and command catalog lists every tool.

  • It cannot reach another organization. The organization is fixed by the credential, not by anything the agent asks for.
  • It cannot widen its own access by asking.
  • It cannot remove a module whose slices have started: Studio refuses the removal unless every slice in it is still Not started.

Changes the agent makes show up on the board like anyone else’s, and in the board’s history.

If the secret leaks, or you lose track of who has it, select Rotate secret under Settings > MCP. Studio generates a new secret immediately, and the old one stops working at once. Every agent that used the old one has to be reconfigured with a new token.