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.
Before you start
Section titled “Before you start”- 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.
Find the endpoint and the credential
Section titled “Find the endpoint and the credential”- Open Settings > MCP.
- Read the Endpoint and the Client ID. The client ID is your organization’s name, so it is not a secret.
- Next to Client secret, select Show to reveal the secret. Select Hide when you are done.
- 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.
Get a token
Section titled “Get a token”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.
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.
Point your agent at Studio
Section titled “Point your agent at Studio”Most MCP clients take a URL and a header. With Claude Code:
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.
Check that it worked
Section titled “Check that it worked”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.
What the agent can do
Section titled “What the agent can do”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.
What the agent cannot do
Section titled “What the agent cannot do”- 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.
Rotate the secret
Section titled “Rotate the secret”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.