Integrate the Matomo MCP Server with Microsoft Copilot Studio

Before you start

1. The MCP Server is included with Matomo Cloud. For Matomo On-Premise, you will need to first install and activate the MCP Server plugin.
2. In both Matomo environments, the MCP will need to be manually enabled in Matomo before use. Refer to the guide on configuring the MCP Server.
3. Ensure you have access to Microsoft Copilot Studio with permissions to publish apps.
4. To isolate permissions and limit access to analytics data, you can optionally create a dedicated Matomo user account for MCP access. For example, assign View access to the MCP user account and ensure the privilege limit is set to View in the Matomo MCP settings.
5. Log in to Matomo as the MCP user and generate an auth token in Matomo. Keep this on hand as you will need it during the setup process to authenticate the connector.

Create a custom connector in PowerApps

1. Open your Microsoft Copilot Studio dashboard, click the ellipsis (…) menu and select Power Apps.

2. In the Power Apps platform, click More > Discover all.
   

3. Locate the Data tile and select Custom connectors.
   

4. In the Custom connectors page, click New custom connector > Create from blank.
   

5. Provide a unique and descriptive name, for example, Matomo Analytics MCP Server.
6. Click Continue.
7. It is optional to upload a custom logo and add a Description detailing the purpose of the app.
8. Use the toggle to enable the Swagger editor.
9. Copy the code below and paste in the Swagger editor, overwriting all existing content.
   
10. Replace the host URL $MATOMO_DOMAIN with your Matomo URL, for example, mysite.matomo.cloud.

swagger: '2.0'
info:
  title: Matomo Analytics MCP
  description: Matomo Analytics MCP Connector
  version: '1.0'
host: $MATOMO_DOMAIN
basePath: /
schemes:
  - https
paths:
  /index.php:
    post:
      summary: Matomo Analytics MCP
      x-ms-agentic-protocol: mcp-streamable-1.0
      operationId: InvokeMCP
      responses:
        '200':
          description: Success
security:
  - api_key: []
securityDefinitions:
  api_key:
    type: apiKey
    in: header
    name: Authorization

Close the Swagger editor and click Create connector.

Add Policies to the Matomo MCP custom connector

1. After creating the custom connector, open the 2. Security tab.
2. The fields should be populated from the Swagger configuration.
   
3. Go to the next tab, 3. Definition. You will need to add three policies for the required GET parameters.

4. At the bottom of the page under Policies, click the plus + icon to add a new policy.
   

5. Define Policy 1:

   • Name: Parameter: module
   • Template: select Set query string parameter
   • Operations: select InvokeMCP
   • Query parameter name: module
   • Query paramter value: API
   • Action if query parameter exists: select override
     

6. Define Policy 2:

   • Name: Parameter: method
   • Template: select Set query string parameter
   • Operations: select InvokeMCP
   • Query parameter name: method
   • Query paramter value: McpServer.mcp
   • Action if query parameter exists: select override
     

7. Define Policy 3:

   • Name: Parameter: format
   • Template: select Set query string parameter
   • Operations: select InvokeMCP
   • Query parameter name: format
   • Query paramter value: mcp
   • Action if query parameter exists: select override
     

8. Click Update connector and close.

Add the Matomo MCP connector to your Agent

1. Open Copilot Studio and select Agents.
2. Edit an existing agent or create a new one.
3. In the Agent’s configuration, go to the Tools menu.
4. Click + Add a tool and search for the newly added Matomo MCP custom connector.
   
5. After selecting the custom connector, you will be prompted to setup the connection. Click Create new connection.
   
6. Enter the api_key with the complete header value: Bearer $YOUR_TOKEN_AUTH.
7. Replace $YOUR_TOKEN_AUTH with the auth token generated by the Matomo MCP user.
8. Click Create and then click Add.
9. If the connection is successful, the Tool details will display the Matomo MCP Tools list.
   
10. Test the agent by querying your Matomo analytics data.
    
11. You can choose to publish and share the agent with other users in your organisation.

Troubleshooting the Matomo MCP connection

If you get connection failed errors, check the following:

1. The MCP Server is enabled in the Matomo MCP Server settings.
2. The Matomo URL in the Swagger definition matches your Matomo instance exactly.
3. The custom connector includes all three required policies:
   • module=API
   • method=McpServer.mcp
   • format=mcp
4. The auth token was generated from the same Matomo instance and is still valid.
5. The connection uses the complete Authorization header value (including the word Bearer). Do not enter only the token value.
   Bearer $YOUR_TOKEN_AUTH
6. The Matomo user associated with the API token has permission to access the website you want to analyse.
7. The user does not exceed any configured Maximum allowed MCP privilege level restrictions.
8. After modifying the custom connector, click Update connector before creating a new connection.
9. If the connection still fails, delete the existing connection, create a new one, and generate a new auth token before testing again.