> For the complete documentation index, see [llms.txt](https://docs.tonic.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tonic.ai/textual/tonic-textual-api/textual-mcp-server.md).

# Using the Textual MCP server

## About the Textual MCP server <a href="#mcp-server-about" id="mcp-server-about"></a>

The Textual MCP server is at `/api/mcp`, and registered as `tonic-textual / "Tonic Textual"`.

It uses the stateless streamable HTTP transport. Every MCP message is an independent, authenticated POST.

## Available tools on the Textual MCP server

The Textual MCP server exposes the following tools:

* `upload_files_to_dataset` - Allows you to:
  * Create a dataset.
  * Upload files to a dataset.
* `redact_text` - Redacts or synthesizes detected entities in a plain text string.
* `redact_json` - Redacts or synthesizes detected entities in JSON.
* `redact_html` - Redacts or synthesizes detected entities in HTML.
* `list_entity_types` - Lists the available built-in and custom entity types.

## Authenticating to the Textual MCP server

To authenticate, you use a Textual API key:

* `Authorization: ApiKey <api key>`

## Enabling the Textual MCP server on a self-hosted instance <a href="#mcp-server-enable-self-hosted" id="mcp-server-enable-self-hosted"></a>

On a self-hosted instance, to enable and configure the Textual MCP server, use the following [environment variables](/textual/textual-install-administer/configuring-textual/textual-env-var-configure.md):

* `SOLAR_ENABLE_MCP_SERVER` - Whether to enable the Textual MCP server. The default is false. To enable the MCP server, set this to true.
* `SOLAR_MCP_UPLOAD_TOKEN_LIFETIME_MINUTES` - The lifetime in minutes of the upload token that the tool generates. The default is 60.

## Enabling the Textual MCP server on Claude <a href="#mcp-enable-on-claude" id="mcp-enable-on-claude"></a>

To connect Claude Code to a Textual instance, either:

* From the Claude CLI, add the server:

{% code overflow="wrap" %}

```
claude mcp add -t http tonic-textual https://<your-textual-host>/api/mcp \
  -H "Authorization: ApiKey <your-api-key>"
```

{% endcode %}

* Configure it directly in either:
  * **.mcp.json** - for the project scope. Note that you should not commit an API key to a repository.
  * **\~/.claude.json** - for the user scope

{% code overflow="wrap" %}

```
{
  "mcpServers": {
    "tonic-textual": {
      "type": "http",
      "url": "https://<your-textual-host>/api/mcp",
      "headers": {
        "Authorization": "ApiKey <your-api-key>"
      }
    }
  }
}
```

{% endcode %}

## MCP call workflow

When you make a call to the MCP server:

1. The AI client calls the appropriate MCP Server tool and provides the request parameters.
2. The server verifies that the API key includes the required permissions.
3. The server completes the requested action and returns the results.

For example, for the following prompts:

* `Upload the file Transcript_12345_20240121.txt from the current folder to the dataset New Test Dataset in Textual.`
* `Create a dataset in Textual called Test dataset 2.`

The basic workflow is as follows:

1. The AI client calls `upload_files_to_dataset` and provides:
   * `datasetName` - The name of the dataset. If the dataset does not already exist, then Textual creates it.
   * `fileNames` - A list of files to upload to the dataset, if the request included files to upload.
2. The server:
   1. Checks whether the API key includes the required permissions.
   2. Checks whether the provided dataset exists.
   3. If the dataset does not exist, creates it.
   4. Mints a short-lived, HMAC upload token that is bound to the combination of user and dataset. If the token expires while the request is still in progress, the client requests another token.
3. The tool returns a pre-signed upload URL to allow the file uploads to occur.
4. The upload endpoint:
   1. Validates the HMAC.
   2. Re-checks that the user and account are still valid
   3. Applies the account limits on word count and usage.
   4. Uses a content hash to deduplicate the files.
   5. Uploads the files.
   6. Starts a job to de-identify the uploaded files.


---

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tonic.ai/textual/tonic-textual-api/textual-mcp-server.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.