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

# Material MCP Server

## **Why use the Material MCP?**

The Material MCP server enables you to connect AI clients like Claude, Codex, and Cursor to Material. It lets you query your data in Material in plain language without leaving your AI workspace.

Use it to investigate threats, pull account and message context, manage trusted entities, combine Material data with signals from the rest of your stack, and design your own workflows and uses entirely!

{% embed url="<https://app.arcade.software/share/U1Qgsxxapin7utfADXBy/J2trbLMLLFi1usGTv7j4>" %}

* What the Material MCP is best for:
  * **Investigating security incidents** (for example, "show me open email threat issues" or "look up a user's email threat history")
  * **Contextualizing threats across your stack**: combine Material with logging, threat intel, infrastructure, and vulnerability data
  * **Streamlining security workflows:** natural language instead of manual console navigation or API calls
  * **Targeted AI triage:** feed flagged or high-signal emails to an AI without pulling everything

{% hint style="danger" %}

#### What the MCP isn't for

The Material MCP does **not** replace Material verdicts. For verdict decisions, trust Material’s detection engine. It is purpose-built for email threat analysis at a depth and scale that general-purpose AI is not designed to match on its own.

Use AI to add context around Material’s findings. It works well for combining Material data with signals from tools that Material doesn't have access to like your SIEM, identity provider, ticketing system, or threat intel platform.
{% endhint %}

***

## Before you begin

To use the Material MCP, you need an account with an AI client that supports MCP, which nearly all do. Material provides documentation for many AI clients below.&#x20;

You can connect in one of two ways:

* **OAuth:** authorize the connection and let the OAuth protocol handle token management and refresh
* **API token:** generate a static token in Material and provide it to your AI client

## How to connect

### One: Enable the MCP Server

{% hint style="success" %}
To enable the MCP server, you need a Super Admin, Tenant Admin, Global Settings Admin, or Settings Admin [role](https://docs.material.security/learn-more/administration/admin-roles).
{% endhint %}

1. From the top tool bar, click **Integrations**.
2. From the left navigation, expand **API and MCP** then click **Settings**.
3. Toggle the MCP Server to **On** then **Save**.

   <figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2FgA2pJDWSIGfTmTfXeKvk%2Fimage.png?alt=media&#x26;token=678a3037-b620-408d-95d9-b07af2caa3f3" alt="Integrations settings page showing the MCP Server toggle turned on"><figcaption></figcaption></figure>

{% hint style="info" %}
If you have multiple tenants, you can enable/disable the MCP server on a tenant-by-tenant basis. From the tenant screen, choose to inherit the global setting or set custom.

<img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2FBQgc1kRo35J9HfDlW2sM%2Fimage.png?alt=media&#x26;token=cb01fdec-c552-40ee-b553-59bb5359d177" alt="At the tenant level, you can inherit the global MCP setting or override it." data-size="original">
{% endhint %}

### Two: Connect your AI tool

#### Connect with OAuth

1. From the top toolbar, click **Integrations**.
2. Expand **API and MCP**, then click **Tokens and MCP Connections**.&#x20;
3. Click **Connect to MCP** to open the setup dialog.
4. Select your AI client to see setup instructions tailored to it, then sign in to authorize the connection.

<figure><img src="/files/D84GMwfcjc0im4EUpCvB" alt=""><figcaption></figcaption></figure>

#### Connect with an API token

If you'd rather use a long-lived API token, use the per-client steps below or follow the in-product guidance.

<details>

<summary>Connect to Claude Code via the terminal</summary>

Before you begin, make sure you have Claude Code installed. If you don't, review [Claude Code's documentation](https://code.claude.com/docs/en/overview).

1. In Material, from the top toolbar click **Integrations**.
2. Expand **API**, then click **Tokens**.
3. Click **Create Token**. Review Authentication for best practices.
4. On the API Tokens screen, under **Connect to MCP** click **Claude Code**.

   <figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2FSpr6GZVImjO74CzCFOEU%2Fimage.png?alt=media&#x26;token=a2fd59a4-7ce3-4416-ad12-f5095fc93c40" alt="" width="375"><figcaption></figcaption></figure>
5. Click the **code block** to copy the command to your clipboard. Your token is auto-populated in the snippet.
6. Open your terminal, paste the command, and click **Enter**.
7. In Claude Code, run `/mcp` to confirm that Material is listed as a connected server.

Need to disconnect? See [How to disconnect the Material MCP](#how-to-disconnect-the-material-mcp).

</details>

<details>

<summary>Connect to Claude Desktop</summary>

Before you begin, install [Node.js](https://nodejs.org/) (v18 or later) if you don't already have it. Node.js includes `npx`, which is required to connect to the Material MCP server with Claude Desktop.

To verify `npx` is installed, run `which npx`. If installed, the command returns a file path. For example: `/Users/your-name/.nvm/versions/node/v22.22.0/bin/npx`.

***

**Connect to Claude Desktop**:

1. In Material, from the top toolbar click **Integrations**.
2. Expand **API**, then click **Tokens**.
3. Click **Create Token**. Review Authentication for best practices.
4. On the API Tokens screen, under **Connect to MCP** click **Claude Desktop**.

   <figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2FKdAlgKEf6n2i92Nanwvt%2Fimage.png?alt=media&#x26;token=dcf00b60-f11a-434b-afef-caab57bff82b" alt="" width="375"><figcaption></figcaption></figure>
5. Open your `claude_desktop_config.json` file. It's located at:

* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`
* **Linux:** `~/.config/Claude/claude_desktop_config.json`

{% hint style="success" %}
You can also ask Claude Code to assist you in updating this file.
{% endhint %}

6. Paste the bock from step 4 immediately after the opening `{`, before any existing content.
7. Save the file, then fully quit and relaunch Claude Desktop (on macOS, use **Claude > Quit Claude**, not just the red close button).
8. To confirm the connection, click your name in the bottom-left corner of Claude Desktop, then click **Settings**, then **Developer**. You should see the Material MCP server with a **running** badge.<br>

   <figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2FF7rxibIKC9Q8PupWiWnJ%2Fimage.png?alt=media&#x26;token=97235e32-0ebf-4257-8c73-5681e98bee32" alt="Claude Desktop Developer settings showing the Material MCP server with a running badge"><figcaption></figcaption></figure>
9. To verify the tools are working, open any Claude tool (Chat, Cowork, or Code) and enter a prompt like "**Using the Material MCP, show me the 5 most recent issues.**" Claude should return a list of 5 issues from Material.

   <figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2F2kegnOxsi2g16QuyAI21%2Fimage.png?alt=media&#x26;token=7867eb2d-990b-4938-b7e7-411f20e79ae9" alt="Claude chat returning the five most recent Material issues after a prompt using the Material MCP" width="563"><figcaption></figcaption></figure>

Need to disconnect? See [How to disconnect the Material MCP](#how-to-disconnect-the-material-mcp).

</details>

<details>

<summary>Connect to Cursor</summary>

Before you begin, make sure you have Cursor installed. If you don't, review [Cursor's documentation](https://cursor.com/docs/get-started/quickstart).

1. In Material, from the top toolbar click **Integrations**.
2. Expand **API**, then click **Tokens**.
3. Click **Create Token**. Review Authentication for best practices.
4. On the API Tokens screen, under **Connect to MCP** click **Cursor**.

   <figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2FVSzqFawtjhxC6Rw2DWAK%2Fimage.png?alt=media&#x26;token=36692ed3-1261-4f3c-afee-cfc272d697fb" alt="" width="375"><figcaption></figcaption></figure>
5. Click the **code block** to copy the configuration to your clipboard. Your token is auto-populated in the snippet.
6. In Cursor, open **Settings > Tools & MCP** and open your `~/.cursor/mcp.json` file.
7. Paste the configuration into the file and save.
8. Restart Cursor and confirm that Material appears as a connected server under **Settings > Tools & MCP**.

Need to disconnect? See [How to disconnect the Material MCP](#how-to-disconnect-the-material-mcp).

</details>

***

## Available tools

The Material MCP gives your AI client access to the following tools:

* [**List issues**](https://docs.material.security/reference/api-v1/issues): retrieve a filtered list of issues, such as all open high-severity issues or issues from a specific sender
* [**Get issue**](https://docs.material.security/reference/api-v1/issues): retrieve the full details of a single issue
* [**Update issue**](https://docs.material.security/reference/api-v1/issues): update the status, severity, or assignee on an issue, or take remediation actions like deleting messages, adding warning banners, or redirecting links and attachments
* [**Get message**](https://docs.material.security/reference/api-v1/messages): retrieve the full details of a single email message associated with an issue
* [**List trusted entities**](https://docs.material.security/reference/api-v1/trusted-entities): review the domains, email addresses, and IP addresses or CIDR ranges your instance trusts
* [**Get trusted entity**](https://docs.material.security/reference/api-v1/trusted-entities): retrieve a single trusted entity and its settings
* [**Create trusted entity**](https://docs.material.security/reference/api-v1/trusted-entities): add a new trusted entity
* [**Update trusted entity**](https://docs.material.security/reference/api-v1/trusted-entities): change a trusted entity's settings, such as disabling it
* [**Delete trusted entity**](https://docs.material.security/reference/api-v1/trusted-entities): remove a trusted entity you've added

{% hint style="warning" %}
The trusted entity tools change what Material trusts. Creating, updating, and deleting trusted entities are security-sensitive, audited actions that require the trusted entities write permission. System-managed entities can't be deleted.
{% endhint %}

### Example prompts to get started

Here's what usage of the Material MCP server looks like in some common AI clients:

<figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2FB1VBr1XzFXnZlowxXbC0%2Fimage.png?alt=media&#x26;token=96b93c98-9566-43e9-b24d-875b2c9b1923" alt="" width="563"><figcaption><p>Example in Claude Desktop</p></figcaption></figure>

<figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2F41gUvhdQ15RWpHZ17z2N%2Fimage.png?alt=media&#x26;token=0b1204f7-72e0-42ce-9524-ec684217b4d6" alt="Example AI chat showing threat investigation prompts using the Material MCP"><figcaption><p>Example in Claude Code via the terminal</p></figcaption></figure>

Try these prompts to get started, or use them as a starting point for your own:

<details>

<summary><strong>Incident triage</strong></summary>

* Show me the 10 most recent open email threats. Include the issue ID, name, sender, severity, and classification.
* Do any of these share sender infrastructure, themes, or content patterns that suggest coordinated activity, or do they look like distinct one-off attacks?
* Show me flagged emails from this week that haven't been reviewed yet

</details>

<details>

<summary><strong>Filtering and prioritizing</strong></summary>

* Show me all open high-severity email threats from the last 7 days
* How many open issues are there right now, and how many are high severity?
* Show me all unresolved issues from this week, sorted by severity

</details>

<details>

<summary><strong>User history</strong></summary>

* Has \[user/account] been targeted by any high-severity threats recently?

</details>

<details>

<summary><strong>Deep dive</strong></summary>

Pick the highest-risk issue from \[a list of issues you just pulled]. Pull its full details including messages, links, attachments, and any indicators of compromise. Summarize who received it, what the lure is, and what the payload is.

</details>

<details>

<summary><strong>Remediation</strong></summary>

* Mark this issue as in progress, escalate severity to high, and apply remediation: add a warning banner, block all links and attachments, and notify anyone who reported it including anyone who already reported it.
* Show me the current state of that issue and confirm what changed.

</details>

<details>

<summary><strong>Trusted entity management</strong></summary>

* Show me all trusted external domains that are currently enabled.
* Add partner.example.com as a trusted external domain, including its subdomains.
* Temporarily disable the trusted entity for example.com without deleting it.

</details>

## Rate Limiting

The MCP server is subject to rate limiting in the underlying API.

***

## Troubleshooting

<details>

<summary><strong>Authentication errors</strong></summary>

* `401 Unauthorized` **error**: your token may be missing or invalid. Verify that your token was copied correctly and hasn't been disabled. See Authentication to generate a new token.
* If you see an "Authorization failed" error in your AI client, check that the token is correctly included in your configuration.

</details>

<details>

<summary><strong>Connection not working</strong></summary>

* In Claude Code, run `/mcp` to check that Material is listed as a connected server.
* In Cursor, open **Settings > Tools & MCP** and confirm Material appears as a connected server.

If Material isn't listed, revisit the connection steps for Claude Code or Cursor.

</details>

<details>

<summary><strong>Disconnect the Material MCP</strong></summary>

**Disconnect from Claude Code**

To disconnect Material from Claude Code, run the following command in your terminal:

`claude mcp remove material`

**Disconnect from Cursor**

To disconnect Material from Cursor, open your `~/.cursor/mcp.json` file, remove the Material configuration block, and save the file.

</details>

<details>

<summary><strong>Remediation behaving unexpectedly</strong></summary>

* If you apply `delete` alongside other remediation actions like `addBanner`, the additional actions are dropped silently. This is expected. Once a message is deleted, actions like banners and link blocking are no longer applicable.
* Updating remediation on an issue replaces the entire remediation list, it doesn't add to it. If you want to preserve existing remediation actions, include them explicitly in your request.
* To notify users who previously reported an issue, explicitly ask your AI client to include previous reporters. Without this, existing notification settings may be cleared.

</details>

<details>

<summary><strong>Slow or no responses</strong></summary>

The MCP may take longer to respond when retrieving large numbers of issues or messages. Try narrowing your request with filters like a date range, severity, or status.

</details>

If these troubleshooting sections don't resolve your issue, or you are unable to connect to the Material MCP server from your preferred AI client, contact Support. We're happy to help.


---

# 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.material.security/reference/material-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.