> ## Documentation Index
> Fetch the complete documentation index at: https://squad.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Squad's tools for AI apps

> Look up each tool that Squad's MCP server gives a connected AI app, what it takes, what it returns, and the messages it can give.

This page lists the tools that an AI app gets when you connect it to Squad. To connect an app, see [Use Squad from Claude, ChatGPT, or Cursor](https://squad.so/docs/use-squad-from-ai-apps.md).

## The server

| Item | Value |
| - | - |
| Address | `https://squad.so/mcp` |
| Transport | Streamable HTTP. Each request gets its answer as JSON. The server keeps no stream open. |
| Sign-in | **Sign in with Squad**: OAuth 2.1 with PKCE (S256) and dynamic client registration. The app finds the sign-in from the server's first answer. |
| Who the tools work as | The person who connected the app, with that person's role and the teammates that the person can use. |
| Where you see the apps signed in as you | **Settings** > **You** > **Apps signed in as you**. See [See and disconnect your apps](https://squad.so/docs/use-squad-from-ai-apps.md#see-and-disconnect-your-apps). |

For how long a sign-in request waits, and the caps on the tools, see [Limits and defaults](https://squad.so/docs/limits-and-defaults.md#use-squad-from-other-apps).

## Choose the squad

Every tool except `list_squads`, `find_dashboard_action`, and the two run tools takes an optional `squad`: a squad's id or its name from `list_squads`. When you leave it out, the tool uses the squad that you opened last in Squad, on the web or on Squad for Mac. With none, it uses your first squad.

A teammate is named by its id, its full name, or its first name. Upper and lower case do not matter, and a leading `@` is dropped. Only teammates that you can use count. People are not teammates.

## Tools

The **Changes something** column says whether the tool changes anything in Squad. Some AI apps let tools that only look something up run without asking, and ask you before the others.

| Tool | What it does | Takes | Changes something |
| - | - | - | - |
| `list_squads` | Lists the squads that you belong to, with `owner` for a squad that you own and `member` for one that you joined. It marks the squad that you opened last, and a squad that is still being set up. | Nothing | No |
| `whats_waiting` | Lists the open questions and approvals that your teammates are waiting on you for: the ones for you, and the ones for no one in particular. A question that a teammate asked of another person is not listed. Each has its id, its kind (`approval`, `decision`, `access`, `action`, or `input`), what it asks, the answers or options it offers, and the task that it is about. A question that you set for later is listed too, with `setForLater` and `backAt`, the time when it comes back. See [Set a question for later](https://squad.so/docs/tickets.md#set-a-question-for-later). With none, it says "Nothing needs you right now." | `squad` | No |
| `list_teammates` | Lists the AI teammates in the squad that you can use, with their role, and marks the chief of staff. | `squad` | No |
| `message_teammate` | Sends a message to one teammate, as you would in chat. It starts a new conversation unless you name one. With `wait_seconds`, it waits for the reply and returns it. | `teammate` and `text` (required), `conversation`, `wait_seconds`, `squad` | Yes |
| `message_squad` | Posts in Squad chat, where every teammate can read and answer. Name a teammate with @ and the name. When Squad chat cannot take the message, it says why. | `text` (required), `squad` | Yes |
| `list_conversations` | Lists your latest conversations with one teammate, newest first: how each began, its latest message, and when it last moved. | `teammate` (required), `squad` | No |
| `read_conversation` | Returns the latest messages of a conversation with one teammate. Without `conversation`, it reads your latest conversation with that teammate. | `teammate` (required), `conversation`, `limit`, `squad` | No |
| `list_tasks` | Lists the open tasks that your squad is working on, not done or archived ones: title, status, the teammate who has it, and the priority when it is not normal. | `squad` | No |
| `get_task` | Returns one task with its description and its latest comments, each with who wrote it and when. | `task` (required), `squad` | No |
| `create_task` | Creates a task, for one teammate if you name one. | `title` (required), `description`, `teammate`, `priority` (`urgent`, `high`, `normal`, or `low`), `squad` | Yes |
| `comment_on_task` | Adds a comment to a task, as you. Name a teammate with @ and the name. | `task` and `text` (required), `squad` | Yes |
| `answer_question` | Answers one question or approval from `whats_waiting`, as the button in Squad would. See [How answers are read](#how-answers-are-read). | `question` (required), `answer`, `squad` | Yes |
| `find_dashboard_action` | Searches the actions that the dashboard can take, by words, for example "model", "routine", or "inbox". See [Anything else in the dashboard](#anything-else-in-the-dashboard). | `words` (required) | No |
| `run_dashboard_read` | Runs one action that only looks something up. | `action` (required), `args` | No |
| `run_dashboard_change` | Runs one action that changes something, for example a setting, a routine, a teammate, or an email. | `action` (required), `args` | Yes |

### Messages and replies

`message_teammate` returns the conversation's id. Without `wait_seconds`, it returns at once and says to read the reply with `read_conversation`. With `wait_seconds`, it returns the replies to this message when the teammate replies in time. Otherwise it says that the teammate "hasn't replied yet", and you read the reply later with `read_conversation`.

Each message that `read_conversation` returns has who it is from, its text, and its time. It also has, when the message has them:

* The files that it carries, each by name with its link. A deleted file is marked as deleted.
* What its card opens or offers, as Squad shows it: a document, list, email, or task (by id and title), the choices that it offers, or the draft that it proposes.
* A mark that your message still waits for its reply.

### How answers are read

`answer_question` turns the answer into the same answer that a button in Squad sends. Your teammate reads it the same way.

| Kind (`kind`) | Answers that it takes |
| - | - |
| Any kind | `skip` skips the question when it is not needed. The teammate carries on without the answer. |
| An approval (`approval`) | `approve`, `approved`, `yes`, or `y` approves. Any other words ask for those changes. |
| A yes or no question (`decision`, with yes and no as its answers) | `yes`, `y`, or `approve` says yes. `no`, `n`, or `decline` says no. Other words are your own answer. |
| A choice (`decision`, with options) | An option's id or its words. Other words are your own answer. |
| Access (`access`) | `granted`, `yes`, `y`, or `done` marks the access granted. Other words are your own answer. |
| A step to do (`action`) | `done`, `yes`, `y`, or no answer marks it done. Other words are your own answer. |
| A question that asks for words (`input`) | Your words, exactly as you wrote them. An empty answer is refused. |

A question that was already answered is not in `whats_waiting`, and an answer to it is refused.

## Anything else in the dashboard

`find_dashboard_action` returns the best matches for your words. Each match has the action's name, what it does, the arguments that it takes, and which tool runs it:

* `run_dashboard_read` for an action that only looks something up.
* `run_dashboard_change` for an action that changes something. Some actions that may only read, for example on your cloud computer, also go here, because Squad cannot tell in advance that they only read.

An action sent to the wrong run tool does not run. The tool says which one to use.

The actions are the ones that the dashboard itself uses. They run as you, with the same checks as in the dashboard. Ids that an action takes, for example a squad's `workspaceId` or a teammate's `agentId`, come from the other tools.

For example, an app can read and change the deals in **Contacts**: the board, a deal with its steps, and its playbooks, and it can open, change, close, or delete a deal. A deal's money shows only to the owner and Administrators, as in the dashboard. An app can also prepare a backup of your squad and get its download link when it is ready. See [Back up your squad](https://squad.so/docs/settings.md#backup).

### What an app cannot do

These actions are not on the list, so an app cannot run them:

* Changes to what you pay: seats, credit packs, auto-recharge, a [task budget](https://squad.so/docs/costs.md#budgets-for-a-task), your subscription and its billing portal, and payment cards and who can use them.
* Signing in to Squad, and the apps signed in as you. An app cannot connect or disconnect apps.

A teammate's inbox can be added or removed through an app only when it does not need a paid seat. When it needs one, the app gets "Changes to what you pay are made in Squad itself. Open Squad to make this one."

## Messages from the tools

A tool that cannot do what was asked returns a message instead of a result. Messages from Squad's own checks are passed on as Squad wrote them.

| Message | Cause |
| - | - |
| You aren't in a squad called "…". See list\_squads. | No squad that you belong to has that id or name. |
| You aren't in a squad yet. Set one up at squad.so first. | You do not belong to any squad. |
| No teammate called "…" in this squad. Teammates: … | No teammate that you can use has that id or name. The message lists the ones that you can use. |
| You have no conversations with … yet. | `read_conversation` found no conversation with that teammate. |
| No task with that id in this squad. | The task id is wrong, or the task is in another squad. |
| No open question with that id in this squad. | The question was answered, closed, or is in another squad. |
| Say your answer: this question needs one. | The question needs an answer, and none was given. |
| Say which … | A required value is missing, for example the teammate or the text. |
| No dashboard action called "…". Find one with find\_dashboard\_action. | The action name is not on the list. |
| … changes something; run it with run\_dashboard\_change. | A change was sent to `run_dashboard_read`. |
| … only looks something up; run it with run\_dashboard\_read. | A lookup was sent to `run_dashboard_change`. |
| Changes to what you pay are made in Squad itself. Open Squad to make this one. | The action would add or release a paid inbox seat for a teammate. |
| Only the squad owner can answer this question. | Only the owner can answer a request for access (`access`) or a step to do (`action`). |
| Only …, the owner or an Administrator can answer this request. | A teammate asked another person for access (`access`) or a step to do (`action`). Only that person, the owner, or an Administrator can answer it. See [Who can answer](https://squad.so/docs/tickets.md#who-can-answer). |
| Squad chat couldn’t take that message. | `message_squad` could not post, and Squad gave no other reason. |
| No dashboard action matches. Try other words; there are … actions in all. | `find_dashboard_action` found nothing for those words. |

The sign-in has its own messages. See [Troubleshooting](https://squad.so/docs/use-squad-from-ai-apps.md#troubleshooting).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.