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

# MCP Tool Reference

> Every tool the Delphina MCP server offers, and who can use it

The [Delphina MCP server](https://docs.delphina.ai/integrations/delphina-mcp) offers the tools below. Which ones your client sees depends on your role and on whether its connection has [administrative access](https://docs.delphina.ai/integrations/delphina-mcp#administrative-access).

## Everyday tools

Every member gets these. They act as you, so a tool returns exactly what you would see in the web app and nothing more — your workspaces, your chats, the knowledge you can already read. The administrative tools further down are separate and need [administrative access](https://docs.delphina.ai/integrations/delphina-mcp#administrative-access).

### Workspaces and setup

| Tool | What it does |
| - | - |
| `list_workspaces` | List the workspaces you can act in, with each one's `id` and `name` (either works as a selector), your role, and whether it is the default that tools use when you don't name a workspace. Most tools take a `workspace` argument. |

### Asking a question

The normal flow is `start_chat`, then `wait_for_turn`, then `get_turn_result`.

| Tool | What it does |
| - | - |
| `start_chat` | Ask Delphina's analytics agent a question. It answers from the workspace's warehouse using your curated metric definitions and returns numbers, charts, and a written summary. |
| `send_message` | Send a follow-up in a chat you own. Creates a turn and queues the agent. |
| `wait_for_turn` | Wait for one turn to finish. `wait_for_turns` does the same for several at once. |
| `get_turn_result` | Read the final answer of a completed turn. |

### Reading past work

| Tool | What it does |
| - | - |
| `list_chats` | List the chats you can read, with overview metrics, newest first. Paginated — check `has_more` and page with `offset`. Covers every workspace you belong to unless you name one. |
| `search_chats` | Keyword search across the content of chats you can read: what people asked, what the agent answered, the files it produced, titles and owners. The fastest way to find earlier work on a metric, table, or error before reading it in full. |
| `get_chats` | Metadata and document URLs for up to 20 chats at once, by ID or Delphina URL. A chat you can't reach returns an error entry instead of failing the whole call. |
| `get_turns` | Turn metadata for one chat: status, mode, timestamps, and message counts. |
| `get_turn_messages` | The messages within a turn. |
| `list_chat_files` | Every persisted file on a chat — uploads and everything the chat produced, including artifacts the web UI renders as blocks rather than file tiles. |
| `get_chat_files` | Fetch specific files from a chat. |

### Knowledge

These read your [Context Factory](https://docs.delphina.ai/context-layer.md) knowledge base: the curated metrics, tables, notes, and rules the agent reasons over.

| Tool | What it does |
| - | - |
| `search_knowledge` | Keyword search over the knowledge base. Returns the best-matching documents, name matches first, each with a snippet. Code blocks are searched only when you ask for them. |
| `list_knowledge_documents` | List documents in path order, optionally scoped to one namespace (and anything nested under it) or one document type. |
| `read_knowledge_document` | Read one document by the path the two tools above returned. Long documents come back in pages. |

> [!NOTE]
>
> The knowledge base holds **definitions, not data**. To get a number, use
> `start_chat` — it already applies these definitions. Read the knowledge base
> directly when you want your own agent to reason over your definitions, for
> example to write SQL that matches how your team defines a metric.

### Projects

| Tool | What it does |
| - | - |
| `list_projects` | The Projects you own in a workspace, most recently active first, with each one's ID, chat count, and file count. Projects other people own are not listed. |
| `set_chat_project` | Move a chat you own into a Project. From the next turn it sees the Project's files and instructions and can publish files back. |
| `remove_project_resource` | Detach a chat from its current Project. Never edits or deletes the chat itself. |

## Org admin tools

Organization admins get extra tools for the work they would otherwise do on **Org Admin > Usage Limits** and **Org Admin > Users**. The tools appear only for org admins whose connection has administrative access (see [Administrative access](https://docs.delphina.ai/integrations/delphina-mcp#administrative-access)); other members never see them, and the server checks admin status again on every call.

| Tool | What it does |
| - | - |
| `get_spend_caps` | Shows the base monthly cap, the members with their own cap, and where each capped member stands this month: spent so far, percent used, projected month-end percent, and whether they are blocked, on track to exceed, or have headroom. |
| `set_spend_caps` | Sets or removes the base cap, and sets or removes individual members' own caps. Anything you don't name is left as it is. |
| `list_org_users` | Lists members with their user ID, email, name, whether they are an org admin, and their role in each workspace. Pass `include_deactivated` to include deactivated members. |
| `add_org_user` | Adds a person with a role in one or more workspaces. The first workspace becomes their default, and they sign in with that email. |
| `set_user_workspace_role` | Gives a member a role in a workspace (Developer, Explorer, or Viewer), changes it, or removes them from the workspace with role `none`. |
| `set_home_workspace` | Sets the workspace Delphina opens for a member by default. They must already have a role in it. |
| `deactivate_user` | Stops a member from signing in, and stops their API, Slack, and scheduled activity. Nothing they made is deleted. You cannot deactivate yourself. |
| `reactivate_user` | Restores a deactivated member with the workspace roles they had. |

Spend caps are monthly (calendar month, UTC) and in US dollars, measured against the same spend **Usage Limits** shows. A member's own cap replaces the base cap for them, whether higher or lower. When a member reaches their cap, they can't start new agent turns until the month ends, so lowering a cap can block people immediately. The tools tell the assistant to check with you before it changes caps or deactivates anyone.

To use these tools with a token rather than OAuth, the token must carry the `org:admin` scope or be a token without scopes; see [Token authorization](https://docs.delphina.ai/integrations/delphina-mcp#token-authorization).

## Member profile tools

Org admins can read and change the profile details on **Org Admin > Users** that have no other tool: a member's bio and secondary email. Each tool takes the member's user ID from `list_org_users`, needs a connection with administrative access (see [Administrative access](https://docs.delphina.ai/integrations/delphina-mcp#administrative-access)), and acts only on members of your own organization. Workspace Developers with administrative access also see them, but only org admins can use them: Delphina refuses the call for anyone else.

| Tool | What it does |
| - | - |
| `get_member_bio` | Shows a member's bio, the description of them that Delphina's agent reads for context in their chats. |
| `set_member_bio` | Replaces a member's bio, or clears it. Surrounding whitespace is trimmed, and a bio can be up to 5,000 characters. |
| `set_secondary_email` | Sets or replaces a member's secondary email, a second address that signs in to the same account. It must use one of your organization's domains and can't already belong to another account. |
| `clear_secondary_email` | Removes a member's secondary email. |
| `set_bigquery_jobs_project` | Sets a member's jobs project override for BigQuery OAuth connections, or clears it with an empty string. Read the current project in `list_org_users` (`bigquery_jobs_project`, null when unset), and pass the member's `user_id` as `userId`. This selects where jobs run, not where the queried data lives. It does not change service-account connection settings or grant Google project permissions. |

## Workspace membership tools

Org admins and workspace Developers can look up who belongs to the workspaces they administer. Like the org admin tools, these need a connection with administrative access (see [Administrative access](https://docs.delphina.ai/integrations/delphina-mcp#administrative-access)), and Delphina checks your permission for the selected workspace on every call.

| Tool | What it does |
| - | - |
| `list_administered_workspaces` | Lists the workspaces you can administer, with each one's ID, name, and whether it is a system workspace. Org admins see every workspace in their organization; others see the workspaces where they are a Developer. It does not report your own role; `list_workspaces` does. |
| `list_workspace_users` | Lists the members of a workspace you administer, with each member's email, name, and role (Developer, Explorer, or Viewer). Pass a workspace ID from `list_administered_workspaces`. |

## Usage and settings tools

Org admins can read their organization's usage report, settings, and seat limits. These tools need a connection with administrative access (see [Administrative access](https://docs.delphina.ai/integrations/delphina-mcp#administrative-access)) and act on your own organization. Workspace Developers with administrative access also see them, but only org admins can use them: Delphina refuses the call for anyone else.

| Tool | What it does |
| - | - |
| `get_usage_report` | Returns the same report as **Org Admin > Usage**: activity, each person's usage and costs, data app views and the most-viewed apps, contract-priced costs, and the prepaid balance where your contract has one. Covers every workspace, including deleted ones. Leave the inputs empty for the default period, pass a period ID from `list_usage_periods`, or pass a start and end date. Costs are in US dollars, as exact decimal strings (for example `"1234.50"`). |
| `list_usage_periods` | Lists the reporting periods the Usage page offers, newest first, and marks the default one. |
| `get_organization_settings` | Shows your organization's saved settings, including the viewer monthly turn limit and the per-member spend caps (in microcents, keyed by user ID; `get_spend_caps` shows them in US dollars by email). |
| `get_seat_limits` | Shows the seat limit for each role from your in-force contract. |

## Access tools

Org admins can see and change who in their organization may use MCP and API keys. One setting covers both, and a change takes effect on each person's next request; existing tokens and keys are not deleted. System users and service accounts always have access. These tools need a connection with administrative access (see [Administrative access](https://docs.delphina.ai/integrations/delphina-mcp#administrative-access)) and act on your own organization.

| Tool | What it does |
| - | - |
| `get_programmatic_access` | Shows whether access is off, open to everyone, or limited to selected users, and lists the people who can be selected. |
| `set_programmatic_access` | Turns access off, opens it to everyone, or limits it to selected users, and grants or revokes individual people by email without changing anyone else. Switching from everyone to selected users removes everyone you don't grant. A change that would remove your own access is refused unless you confirm it, because it ends your connection. |


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