> For the complete documentation index, see [llms.txt](https://docs.upriverdata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.upriverdata.com/product-usage/agent/mcp/mcp-tools.md).

# MCP Tools Reference

The tools that the Upriver MCP server gives your AI client.

Your AI client decides when to call these tools. You don't call them yourself. In practice, your client calls `ask_upriver` to ask a question (or `create_task` in clients that don't show the live view), and it manages the other tools while the agent works. This page tells you what each tool does, so that you can understand what your client is doing.

## Tools

| Tool                | What it does                                                                                                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_task`       | Starts a new Upriver task with a question or a request, and waits for the answer.                                                                                                                 |
| `send_message`      | Sends a follow-up or an answer to a question on an existing task.                                                                                                                                 |
| `wait_for_task`     | Waits a short time for the agent's current turn. If the turn is not done, it returns `still_running` with the latest steps, and your client calls it again.                                       |
| `list_tasks`        | Lists your recent Upriver tasks.                                                                                                                                                                  |
| `cancel_task`       | Stops the turn the agent is working on. The task keeps its context.                                                                                                                               |
| `get_query_results` | Gets the rows, columns and chart of the queries that the agent ran. It returns up to 200 rows for each query. The full results are in the web app.                                                |
| `ask_upriver`       | Asks a question and shows a live view of the task in the chat, with the agent's steps, questions and answer. Only in clients that support interactive views (MCP Apps), such as Claude and Codex. |

## How a request runs

1. Your client calls `create_task` (or `send_message` for a follow-up on the same task). The call waits a short time for the agent.
2. If the agent is still working, your client calls `wait_for_task` until the status changes. Each result tells your client what to do next.
3. When the turn is done, your client shows you the answer and a link to the task in the Upriver web app.

If it takes a long time to create a task, the task still shows in `list_tasks`.

## Statuses

Each result has one of these statuses:

| Status          | Meaning                                                                                            |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `completed`     | The agent finished its turn. The result has the answer and a link to the task.                     |
| `needs_input`   | The agent asked a question. Your client shows it to you and sends your answer with `send_message`. |
| `still_running` | The agent is still working. The result shows its latest steps.                                     |
| `failed`        | The turn stopped because of an error. The result tells your client if it can try again.            |
| `canceled`      | The turn was stopped. The task keeps its context, so you can continue it.                          |

Some results include values such as `task_id` and `turn_id`. Your client sends these values back in its next call. Their format can change, so do not rely on it in your own code.
