Connecting AI Assistants

Connecting AI assistants (MCP)

Wouldn't it be nice to ask your AI assistant "which approved requirements of the Billing platform have no use case yet?" and get an answer straight from Studio? That's what the optional MCP integration does.

MCP (Model Context Protocol) is an open standard that lets AI clients such as Claude Code, Claude Desktop or Cursor talk to external tools. Studio can expose its artifacts, diagrams and traces through MCP, read-only.

sequenceDiagram
    actor You
    participant AI as AI client<br/>(Claude Code)
    participant MCP as Studio /mcp/post
    participant API as JSON:API (read-only)
    You->>AI: "List the requirements not yet approved"
    AI->>MCP: tool call + Authorization header
    MCP->>API: read artifacts as the mcp_bot account
    API-->>MCP: records the bot may see
    MCP-->>AI: results
    AI-->>You: a friendly answer

Loading

Setting it up

1. Install the MCP recipe (adds the contributed mcp module and JSON:API, read-only):

   vendor/bin/drush recipe $PWD/recipes/divengine_studio_mcp

2. Create the service account and its token:

   vendor/bin/drush divengine:mcp-setup --uri=https://studio.example.com

   This creates the mcp_bot user with the mcp_agent role, writes a random token to private/divengine-mcp.token (outside the web root, never stored in configuration), and prints the command to register Studio in your client.

3. Add Studio to your AI client, e.g. Claude Code:

   claude mcp add --transport http divengine-studio https://studio.example.com/mcp/post \
     --header "Authorization: Basic $(base64 -w0 < private/divengine-mcp.token)"

What agents can read

• Artifacts, diagrams and traces through JSON:API.
• The code of the Developments the bot belongs to, with the code_* tools (code_repositories, code_tree, code_find_files, code_read, code_search). See Code Source.
• Technical documentation extracted from code, with the codedocs_* tools: symbols, parameters, references, HTTP endpoints and snapshot comparisons. See Code docs.
• The database schemas of those Developments, with the database_* tools (database_databases, database_tables, database_table, database_findings, database_changes). See Database schemas.

Good to know

Code documentation

Agents can also read extracted technical documentation through the codedocs_* tools: list documentation sets and snapshots, browse units, search symbols, read parameters and references, list extracted endpoints and compare captures. See Code docs for the tool names and examples.

Enable the codedocs plugin in MCP settings, grant the agent role Read code docs (use code docs), and add the bot to the relevant Developments. The current MCP recipe, Code Docs installation/update and divengine:mcp-setup configure the plugin and role; Development membership remains explicit.

The PHP/TypeScript example scripts populate a neutral shop Development and include read-mcp.py, which reads its documentation through the actual MCP endpoint using the existing private token.

Access and authentication

• Read-only by design. The AI can look, not touch. Your approvals and test results stay in human hands.
• It sees what mcp_bot sees. Add the bot as a member of the Developments you want to expose, nothing more.
• Rotate the token whenever you like: drush divengine:mcp-setup --regenerate.
• Don't want it at all? Skip the recipe, and remove the libraries with composer remove drupal/mcp drupal/jsonapi_schema.