> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/workflow-tips/integrating-with-n8n.md).

# Integrating with n8n AI Agent

Connect an n8n AI Agent to BugBug MCP so the agent can inspect, run, and summarize BugBug test results.

Use n8n's **AI Agent** and **MCP Client Tool** nodes to let an agent work with your BugBug project. For example, the agent can run a named smoke test and return a short report with its status and failure evidence.

{% hint style="info" %}
BugBug MCP requires a **Pro or higher** BugBug plan. This guide requires an n8n version whose MCP Client Tool supports **Streamable HTTP**. BugBug MCP does not provide a legacy SSE endpoint.
{% endhint %}

## Before you start

You need:

* An n8n instance with the **AI Agent** and **MCP Client Tool** nodes.
* A BugBug project and a project API token. In BugBug, open **Integrations** → **API** and copy the project token. Treat it as a secret.
* A named test or suite you want the agent to run.

Use a project API token dedicated to this workflow when possible. It limits the agent to that project and makes revoking the workflow's access straightforward.

## Configure the MCP Client Tool

1. Add an **AI Agent** node to your workflow and connect a chat model to its **Chat Model** input.
2. Add an **MCP Client Tool** node and connect it to the AI Agent's **Tool** input, not its main workflow input.
3. In the MCP Client Tool, choose **HTTP Streamable** or **Streamable HTTP** as the transport and enter this endpoint:

   ```
   https://mcp.bugbug.io/mcp
   ```
4. Create a **Bearer Auth** credential in n8n. Paste the BugBug project API token as the token value; n8n adds the `Bearer` prefix to requests.
5. Select only the tools needed for this first workflow. For a run-and-report flow, start with:
   * `bugbug_list_projects`
   * `bugbug_list_tests`
   * `bugbug_run_test`
   * `bugbug_watch_run_progress`
   * `bugbug_get_test_run`
6. Save the credential and let n8n load the selected MCP tools.

{% hint style="warning" %}
Do not put the API token in a prompt, a Set node, workflow JSON, source control, or an n8n expression that exposes it in execution data. Store it only in n8n credentials.
{% endhint %}

## Give the agent a narrow instruction

Add this to the AI Agent's system message, replacing the placeholders:

{% code title="AI Agent system message" %}

```
You are the QA assistant for the <project> BugBug project.

When asked to run a test, first find the exact matching test. If more than one
test matches, ask the user to choose. Run only the explicitly requested test;
do not create, edit, delete, import, stop, or rerun tests.

Wait for the run to finish. Report the test name, final status, a link or ID for
the run when available, and the failed-step evidence when it fails. If the
request does not name a test, ask a clarifying question instead of choosing one.
```

{% endcode %}

This keeps the initial workflow limited to reading project data and running an explicitly named test. Add tools that create, update, delete, import, or change visual-regression baselines only when the workflow has a clear human-approval step.

## Test the workflow

Trigger the workflow with a request such as:

> Run the Checkout smoke test and summarize the result. Do not make any changes.

On the first run, verify that the agent:

1. Finds the intended test instead of selecting a similarly named test.
2. Starts one run only after the request names that test.
3. Waits for completion rather than reporting a still-running status as a result.
4. Returns useful failure evidence, not only “failed.”

## Troubleshooting

| Problem                                            | What to check                                                                                                                                                           |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| n8n cannot load BugBug tools                       | Confirm the endpoint is exactly `https://mcp.bugbug.io/mcp` and the node supports Streamable HTTP. A node that shows only an SSE endpoint cannot connect to BugBug MCP. |
| The server returns `401` or `Invalid bearer token` | Create a new project API token in BugBug and save it as an n8n Bearer Auth credential. Paste the token itself, without `Bearer` .                                       |
| The agent does not call BugBug                     | Confirm that the MCP Client Tool is connected to the AI Agent's Tool input and that the system message tells the agent when to use it.                                  |
| The response says a run is still in progress       | Ensure `bugbug_watch_run_progress` is selected and instruct the agent to wait for the final status.                                                                     |
| The agent chooses the wrong test                   | Require the exact test name in the trigger payload or have the agent ask when there is more than one match.                                                             |

## Next steps

* Learn about the available [BugBug MCP tools](/ai-testing/mcp/mcp-tools.md).
* Review [BugBug MCP setup and security guidance](/ai-testing/mcp.md).
* Use n8n's [AI Agent documentation](https://docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.agent/) for model and trigger configuration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bugbug.io/workflow-tips/integrating-with-n8n.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.