> For the complete documentation index, see [llms.txt](https://help.swarmia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.swarmia.com/settings/integrations/mcp-server/mcp-server-actions.md).

# MCP actions

Ask your AI assistant to set up working agreements, key metrics, initiatives, and more in Swarmia through the MCP server.

Besides answering questions, the Swarmia MCP server can make selected changes in Swarmia for you. When an answer points to something you want to fix, ask your assistant to set it up in the same conversation.

### How actions work

1. Ask in plain language, for example "Set up a working agreement for the Payments team."
2. Your assistant prepares the change, asks for any missing details, and gives you a confirmation link.
3. Open the link in Swarmia, review the change, and confirm or deny it.

Nothing changes until you confirm. Notes are the exception: they're saved right away.

To change a proposal before you confirm it, ask your assistant to revise it. The new proposal replaces the old one. You can also ask your assistant whether a proposal is still pending, confirmed, or denied.

Actions use your existing permissions, so your assistant can't do anything you couldn't do yourself. Learn more about [user roles](/settings/organization/managing-users-and-roles.md).

### Available actions

| Action                                                                                                             | Example request                                                                                                      | Confirmation                                                                      |
| ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Set up a [working agreement](/features/working-agreements.md)                                                      | "Set up a working agreement for the Payments team: pull requests should get a first review within one business day." | Confirm in Swarmia. Name the team explicitly.                                     |
| Save a [key metric](/features/metrics/key-metrics.md)                                                              | "Save change lead time as a key metric under our Delivery goal."                                                     | Confirm in Swarmia. You can create a new goal together with the metric.           |
| Create an [initiative](/features/focus/deliver-strategic-initiatives.md)                                           | "Create an initiative for every story with 'billing API' in the title."                                              | Confirm in Swarmia.                                                               |
| Add a tab to your [pull request inbox](/features/managing-pull-requests-in-progress-with-the-pull-request-view.md) | "Add a tab to my pull request inbox for pull requests in the payments repository that are waiting for review."       | Confirm in Swarmia. The tab is personal.                                          |
| Change [team settings](/features/swarmia-ai.md#changing-team-settings)                                             | "Exclude pull requests with the `dependencies` label from the Payments team."                                        | Confirm in Swarmia. Name the team explicitly. Each change is a separate proposal. |
| Add a [note](/features/notes.md)                                                                                   | "Add a note to this pull request explaining why it took two weeks to merge."                                         | Saved right away and marked as written by Swarmia AI.                             |

{% hint style="info" %}
Your assistant maps your request to the closest supported setting. For example, "a first review within one business day" becomes a review time agreement with a one-day limit that excludes weekends. Check the details before you confirm.
{% endhint %}

### Turn answers into action

Actions work well at the end of an analysis. A few examples:

* After a retro: "Set up a working agreement for my team to keep pull requests under 500 lines."
* After a review bottleneck analysis: "Add a tab to my pull request inbox for pull requests waiting more than a day for a first review."
* After a board summary: "Save change lead time as a key metric under our Delivery goal, so we track it every month."

Find tested questions to start from in the [prompt library](/guides/prompt-library.md).

### What's not supported

Actions can't change organization-wide settings or rewrite historical data.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.swarmia.com/settings/integrations/mcp-server/mcp-server-actions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.