> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://mammoth.io/docs/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# Mammoth MCP server

> Connect Claude, Claude Code, ChatGPT or VS Code to your Mammoth workspace at https://mcp.mammoth.io/mcp. Setup per client, OAuth sign-in and the tool list.

The Mammoth MCP server lets an AI client explore, clean, transform and export your Mammoth data. It is hosted at:

```
https://mcp.mammoth.io/mcp
```

Nothing to install. The transport is streamable HTTP. The client signs you in to Mammoth with OAuth, and every tool call then runs as you, with your permissions. You can limit a connection to some projects, or to reading only, when you approve it.

The MCP server works on every Mammoth plan. It is not the in-app AI Agent: that runs inside the Mammoth web app and is available on Enterprise plans.

## This server and the documentation server

Mammoth has two MCP servers. They do different jobs.

| | Mammoth MCP server | Documentation MCP server |
| --- | --- | --- |
| URL | `https://mcp.mammoth.io/mcp` | `https://mammoth.io/docs/mcp/` |
| Sign-in | OAuth: you approve the connection on a Mammoth consent page | None |
| Reads your workspace | Yes, as you | No |
| Changes your workspace | Yes, as you | No |
| Use it for | Working on your datasets, views, pipelines, dashboards, automations and exports | Looking up how Mammoth works from these docs |

See [Use Mammoth with Claude](https://mammoth.io/docs/agents/claude/) for the documentation server. To act on a workspace from a terminal instead, use the [CLI](https://mammoth.io/docs/agents/).

## Set up your client

### Claude on the web and Claude Desktop

Add a custom connector with this URL, then sign in to Mammoth when Claude asks:

```
https://mcp.mammoth.io/mcp
```

Anthropic's [guide to custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) has the current steps, including how an organization owner adds a connector on Team and Enterprise plans.

**Fewer approval prompts.** By default Claude asks you before every tool call. In the connector's settings, set **Read-only tools** and **Interactive tools** to **Always allow**. Claude then runs reads without asking, and still asks before a tool that changes, deletes or sends out data.

### Claude Code

```bash
claude mcp add --transport http mammoth https://mcp.mammoth.io/mcp
```

Use `--transport http`: the server speaks streamable HTTP, not SSE. Then run `/mcp` inside a session, choose **mammoth** and choose to authenticate; your browser opens the Mammoth consent page. Add `--scope user` to use the server in every project, or `--scope project` to share the entry with your team through `.mcp.json` (each person still signs in as themselves).

### ChatGPT

On the web, in ChatGPT:

1. Go to ChatGPT Plugins, select the plus button, and choose **Add custom MCP server**.
2. Enter a name. Under **Connection**, enter the Server URL:

   ```
   https://mcp.mammoth.io/mcp
   ```

3. Set authentication to **OAuth**. Choose Client ID Metadata Documents (CIMD) if ChatGPT offers the choice: Mammoth supports CIMD and not Dynamic Client Registration (see below).
4. Review the risk warning and confirm with **I understand and want to continue**, then select **Create as a plugin**.
5. Install the plugin. You must install it before you can use it in a conversation, then sign in to Mammoth when ChatGPT asks.

OpenAI's [guide to adding a custom MCP server](https://developers.openai.com/api/docs/guides/custom-mcp-server) has the current steps.

### Cursor

Cursor cannot sign in to the Mammoth MCP server yet. It supports only Dynamic Client Registration, which Mammoth does not offer. In Cursor, use the [Mammoth CLI and its skill](https://mammoth.io/docs/agents/) instead.

### VS Code

Add the server to `.vscode/mcp.json`:

```json
{
  "servers": {
    "mammoth": {
      "type": "http",
      "url": "https://mcp.mammoth.io/mcp"
    }
  }
}
```

Then start the server from the file or the MCP view, and sign in when VS Code asks. The file holds no credential: the client gets its own token through the sign-in below.

## Which clients can connect

Mammoth identifies a client in one of three ways:

- **Client ID Metadata Documents (CIMD).** The client's `client_id` is an `https://` URL that serves a small JSON document naming the client and its redirect URIs. Mammoth fetches that document when the client starts the sign-in. The client sends a PKCE `S256` challenge and needs no secret.
- **The built-in Mammoth CLI client.** The [CLI](https://mammoth.io/docs/agents/) signs in as `mammoth-cli`.
- **An OAuth app registered in a workspace.** A Workspace Owner registers it under **Settings → API Keys → OAuth apps** and gets a client ID, plus a client secret unless the app is a **Public app**. Mammoth accepts only the redirect URIs listed for the app: `https://` URLs, or `http://` URLs on `localhost`, `127.0.0.1` or `[::1]`. For a **Public app**, a listed loopback URI also matches on any port. A sign-in through a registered app is always for the workspace that registered it.

Mammoth does not offer Dynamic Client Registration: its authorization server metadata has no registration endpoint. A client that can only register itself dynamically cannot connect. A client that supports Client ID Metadata Documents can.

Verified to connect: ChatGPT and VS Code. The **Connect an AI assistant** card in **Settings → API Keys** also lists Cursor with a paste-the-URL step; the sign-in still fails there, for the reason above. Claude on the web, Claude Desktop and Claude Code are set up above and use the same sign-in. Not yet supported: Cursor, which supports only Dynamic Client Registration.

## Sign in

1. The client calls the server with no token. The server answers `401` and points the client at Mammoth's authorization server.
2. The client opens a Mammoth consent page in your browser. Sign in to Mammoth if you are not already.
3. Choose the workspace, the projects the client may use (or all projects), and **Read-only** if it should never change anything. Approve.
4. The client receives a token for this server and keeps it. From then on, each tool call reaches Mammoth with that token, as you.

A token belongs to one workspace. A tool call for another workspace is refused. On a read-only connection the server refuses every tool that does not declare `readOnlyHint`, whatever the client asks.

### How long sign-in lasts

- **Access tokens last one hour.** Your client refreshes them automatically, so you do not sign in again every hour.
- **Refresh tokens do not expire on a timer.** Each refresh issues a new refresh token and the old one stops working, so your client must keep the newest one.
- **Each client keeps at most 10 sign-ins.** An 11th signs out the one used least recently.
- **A reused old refresh token revokes the connection.** Mammoth treats it as a possible theft. The client then has to sign in again. One exception: the token that the last refresh replaced still works once for 60 seconds, in case the response never reached the client.

### For client authors

The server follows the MCP authorization spec. Everything a client needs is discoverable:

| | URL |
| --- | --- |
| Server card | `https://mcp.mammoth.io/.well-known/mcp/server-card.json` |
| Protected resource metadata | `https://mcp.mammoth.io/.well-known/oauth-protected-resource/mcp` |
| Authorization server | `https://app.mammoth.io/api/v2` |
| Authorization server metadata | `https://app.mammoth.io/.well-known/oauth-authorization-server/api/v2` |

The server card lists protocol version `2026-07-28`. Sign-in is the authorization code grant with PKCE `S256`, and the client identifies itself with a Client ID Metadata Document or with the client ID of an OAuth app registered in the workspace. A request without a token gets `401` with a `WWW-Authenticate` header whose `resource_metadata` points at the protected resource metadata above.

**Hand-made `mm_` tokens are refused.** The server accepts only tokens issued by this OAuth sign-in. An API token made in **Settings → API Keys** was issued for no server, so it does not work here. Use that token with the [REST API, the SDK or the CLI](https://mammoth.io/docs/build/auth/) instead.

## Revoke access

Open **Settings → Connected apps** in the Mammoth web app and choose **Revoke** next to the client. It loses access at once, including to anything it is doing at that moment. You can connect it again from the client.

## Uploading a file

A tool argument carries only text, so a spreadsheet or a large CSV cannot go through the model. `request_upload` returns a one-time link; you open it (or drop the file on the uploader some clients draw under the call) and the file goes straight from your browser to Mammoth. The link expires after 30 minutes and works for one upload, of a file up to 50 MB. `check_upload` then waits for the file and reports what came of it. [Blast radius and safety](https://mammoth.io/docs/agents/safety/#the-inverse-case-data-entering-mammoth-through-a-link-not-an-argument) explains why this is safe.

A client that can run shell commands can send the file itself. The link is the whole credential, so the request carries no other header, and the form field must be named `data`:

```bash
curl -F "data=@/path/to/sales.csv" "<upload_url>"
```

## In-chat apps

Some clients, Claude among them, support MCP Apps: a small page the server draws in the chat, right under a tool call. Mammoth's server offers three. A client without MCP Apps shows a link instead, and the conversation works the same way.

| Tool | What appears in the chat |
| --- | --- |
| `request_upload` | An uploader. Drop a file on it and it goes to Mammoth without leaving the chat. |
| `connect_source` | A **Connect in Mammoth** button. It opens the connector in the web app, where you sign in to the source; the chat carries on once the connection exists. |
| `preview_query` | The first rows of a database query, with a form to keep it as a dataset. |

The `preview_query` form has these fields, filled in for you:

| Field | Options |
| --- | --- |
| **Dataset name** | The name of the new dataset |
| **Query** | The query to run on the connection |
| **Pull** | **Once, now**, or every so many hours, days, weeks or months |
| **On each refresh** | **Replace the rows** (the default) or **Add the new rows** |

**Create dataset** makes the dataset and posts a message back to the chat so the assistant carries on. If the assistant has already stopped, the uploader and the connect button put a message in your message box for you to send.

## When a call takes a while

A tool call answers within about 30 seconds. A job that runs longer comes back with a `job_id`, and the assistant reads it with `get_job` until it finishes. A call that runs out of time before Mammoth answers says, for example, "add_export took too long to answer, so its outcome is unknown: Mammoth may still be working on it." The work may still go through, so the assistant should read the data before calling the tool again.

## The tools

This list is read from the source of `mammoth-mcp-server` **0.2.12**, the version deployed at `https://mcp.mammoth.io/mcp` on November 5, 2026: 61 tools. The server card at `https://mcp.mammoth.io/.well-known/mcp/server-card.json` reports the version running now; if it is newer, ask your client for the tool list (`tools/list`), which is always current.

Each tool declares what it does to your data as an MCP annotation, so a client can run a read-only tool freely and ask you before a destructive one.

### Tools that only read (`readOnlyHint`): 29 tools

A read-only connection can run only these.

| Tool | What it does |
| --- | --- |
| `aggregate_data` | Have Mammoth work out totals, counts, averages, lows and highs over a view. |
| `check_upload` | Wait for the user to upload their files, and report what came of them. |
| `connect_source` | Give the user the page in Mammoth where they connect a source and bring its data in. |
| `find_new_connection` | Wait for the connection the user makes in Mammoth after `connect_source`. |
| `find_new_datasets` | Find the datasets a project gained since a time: what the user brought in from a source. |
| `get_automation` | Get one automation: what it does, when it runs, and how it last went. |
| `get_dashboard` | Get one dashboard: its title, views, sharing and numbers, and its embed code if asked. |
| `get_data` | Read rows from a view. |
| `get_dataset` | Get one dataset with its columns, row counts and status. |
| `get_export` | Get one export of a view, including how its last runs went. |
| `get_file` | Get one file, with its status and what Mammoth read from it. |
| `get_help` | Explain how Mammoth works. Read this before a first transformation. |
| `get_job` | Read a job a tool named when its call ended before the job did. |
| `get_pipeline` | Get a view's pipeline: its state and its steps, in order, and its versions if asked. |
| `get_schema` | Get what a transformation, an export destination or an automation task takes. |
| `get_view` | Get one view with its columns and their types. |
| `list_automations` | List a project's automations. |
| `list_connections` | List the connections a project has to one source, to bring more data in through. |
| `list_connectors` | List the sources Mammoth can bring data in from: databases, CRMs, ads, files. |
| `list_dashboards` | List the dashboards the signed-in user can open, and the workspace's tags if asked. |
| `list_datasets` | List the datasets in a project. |
| `list_exports` | List a view's exports. |
| `list_files` | List the files uploaded to a project, and its folders. |
| `list_projects` | List the projects in a workspace. |
| `list_tables` | List the tables of a database connection the project already has. |
| `list_trash` | List what is in a project's trash and can still be restored with `undo`. |
| `list_views` | List the views of a dataset. |
| `list_workspaces` | List the workspace this connection belongs to. |
| `preview_transformation` | Show what a transformation would do to a sample of a view, without adding it. |

### Tools that add or change something that can be put back: 11 tools

| Tool | What it does |
| --- | --- |
| `add_transformations` | Add transformations to a view, and run its pipeline once. |
| `create_dashboard` | Create an empty dashboard on a view, and return it. |
| `create_folder` | Create a folder in a project, for files and folder automations. |
| `create_project` | Create a project in a workspace, seen only by the user who made it. |
| `create_view` | Create a view of a dataset, empty or as a copy of another view. |
| `extract_sheets` | Bring the chosen sheets of an uploaded workbook in, one dataset each. |
| `generate_dashboard` | Have Mammoth's AI build a dashboard on a view from a description. |
| `interpret_file` | Say how a file is meant to be read, when Mammoth found more than one way. |
| `rename` | Rename a project, a dataset or a view. |
| `set_file_settings` | Change how a file is read (delimiter, header, rows to skip, quotes) or its date format. |
| `unlock_file` | Open a file that is password protected, so Mammoth can read it. |

### Tools that delete, send data out, publish, or run work (`destructiveHint`): 21 tools

| Tool | What it does |
| --- | --- |
| `add_dataset_from_connection` | Make a dataset from a query on a database connection the project already has. |
| `add_export` | Add an export to a view's pipeline and wait for its first run. |
| `create_automation` | Create an automation in a project and return it. |
| `delete_automation` | Move an automation to the trash. `undo` with what="trash" restores it. |
| `delete_dashboard` | Move a dashboard to the trash. `undo` with what="trash" restores it. |
| `delete_export` | Delete one export of a view. Rows already sent are not taken back. |
| `delete_file` | Delete a file from a project. |
| `delete_transformation_step` | Delete one step of a view's pipeline and wait for the view to run again. |
| `delete_views` | Move views of a dataset, or the whole dataset, to the trash. |
| `edit_dashboard` | Have Mammoth's AI change a dashboard, rename it, set its tags, or choose how it embeds. |
| `edit_export` | Change one export of a view, or run it now. |
| `edit_transformation_step` | Change one step of a view's pipeline, and wait for the view to run again. |
| `manage_draft` | Stage a view's transformations instead of running each one as it is added. |
| `preview_query` | Run a query on a database connection and show its first rows. Nothing is saved. |
| `publish_dashboard` | Publish a dashboard, decide who can open it, and return its link. |
| `request_upload` | Upload a file from the user's computer into Mammoth, as a new dataset or added to one. |
| `review_unreadable_rows` | Show the lines of a file that did not fit, and discard them on request. |
| `run_pipeline` | Run all of a view's steps again, e.g. after its dataset got new data. |
| `undo` | Take a change back: restore trash, roll back a view's pipeline, or remove added batches. |
| `update_automation` | Rename an automation, or stop and start it. Returns it afterwards. |
| `upload_file` | Create a dataset in a project from text you have, or add the text to one it already has. |

A client decides how to act on these annotations. Whether a given client asks you before a destructive tool is that client's setting.

---

**Next up:** [API authentication](https://mammoth.io/docs/build/auth/) for the credential each surface uses · [Blast radius and safety](https://mammoth.io/docs/agents/safety/) for the CLI's mutation classes · [Use Mammoth with Claude](https://mammoth.io/docs/agents/claude/).

---
Source: https://mammoth.io/docs/agents/mcp.md · Updated: 2026-11-02
