> 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, review OAuth apps, manage accounts, groups, and roles, 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, vulnerability, or other 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

***

## 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.

You can connect in one of two ways:

* **OAuth (recommended):** 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. Use this when your AI client doesn't support OAuth.

{% hint style="warning" %}
**Connecting from Claude on a Team or Enterprise plan?** Only an Owner of your Claude organization can add a custom connector, and it's off by default. If you don't see an **Add** button under **Organization settings** > **Connectors**, custom connectors aren't enabled for your organization yet and you'll need an Owner to add Material for you.

This applies to Claude on the web, Claude Desktop, and Cowork. On the Free, Pro, and Max plans you can add your own connector from **Customize** > **Connectors**.
{% endhint %}

<details>

<summary>Ask your Claude organization Owner to add Material</summary>

This is the path we recommend. A connector works across Claude on the web, Claude Desktop, and Cowork, and it supports OAuth, so nobody has to manage a long-lived token.

If you need an Owner to enable this for you, send them something like:

> I'd like to connect Material Security's MCP server to Claude so I can investigate email threats without leaving my AI workspace.
>
> Material publishes a remote MCP server. Adding it takes an Owner, from **Organization settings** > **Connectors** > **Add**, then **Custom** > **Web**.
>
> The server URL is `https://<your-material-instance>/mcp`.
>
> Each person authorizes the connection with their own Material account, so nobody gains access they don't already have. Every request is checked against that account's current permissions, and all activity is recorded in Material's audit log.

Replace `<your-material-instance>` with your Material URL. You can copy the exact Server URL from **Integrations** > **API and MCP** > **Tokens and MCP Connections**, under **Connect to MCP**.

</details>

<details>

<summary>Working in Claude Desktop before a connector is added</summary>

Ask your Owner first. A connector is the better long-term setup for the reasons above, and this route only covers Claude Desktop, not Claude on the web or Cowork.

If you need to work in the meantime, Claude Desktop can also reach an MCP server through a configuration file on your own machine. Your organization controls that separately from its connector list, and it's on by default, so it often still works when the **Add** button isn't there.

Before you set it up:

* **Check with your IT or security team.** Your organization may have left this on deliberately, or may simply not have reviewed it yet.
* **Expect it to be turned off eventually.** IT can disable local MCP servers through device management. If they do, Claude Desktop stops loading the server and you'll need the connector route.
* **You'll manage a token.** This path uses an API token instead of OAuth, so storing and rotating it is on you.

**What to ask your IT team**

Local MCP servers are controlled by a device policy named `isLocalDevMcpEnabled`, which is enabled by default. Your IT team manages it outside Claude's own settings:

* **Windows:** Group Policy or Intune, at `HKLM:\SOFTWARE\Policies\Claude`
* **macOS:** an MDM configuration profile for the `com.anthropic.claudefordesktop` domain

Because this is separate from **Organization settings** > **Connectors**, an organization that hasn't enabled custom connectors may still permit local MCP servers. Ask your team to confirm which of the two they intend to allow. Anthropic documents the full policy list in [enterprise configuration for Claude Desktop](https://support.claude.com/en/articles/12622667-enterprise-configuration-for-claude-desktop).

When you're ready, follow [**Connect to Claude Desktop via an API token**](#connect-with-an-api-token) below.

</details>

## 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

Start here. OAuth is the recommended way to connect: each person authorizes with their own Material account, and token issuing and refresh are handled for you, so there's no long-lived secret to store or rotate.

1. From the top toolbar, click **Integrations**.
2. Expand **API and MCP**, then click **Tokens and MCP Connections**.
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="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2FUe0jp3fQjcN1MDJzeK6g%2Fconnect-to-mcp-oauth.png?alt=media&amp;token=35a0fd6a-1b01-47fc-908a-3e682e52e216" alt=""><figcaption></figcaption></figure>

#### Connect with an API token

Use an API token when your AI client doesn't support OAuth, or when you'd rather manage a long-lived token yourself. Use the per-client steps below or follow the in-product guidance.

<details>

<summary>Connect to Claude Code via an API token in 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 and MCP**, then click **Tokens and MCP Connections**.
3. Click **Create Token**. Name and create a token then copy it and paste it somewhere. You'll need it in the following steps, after you copy another snippet. Tokens are shown **only** at creation time.
4. Return to the **Tokens and MCP Connections** screen.
5. Click **Connect to MCP** > **Claude Code**

<figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2FcoBkd791hQ4ZeNKKLCiQ%2Fimage.png?alt=media&amp;token=7334b1ca-8c40-42b3-91a9-71287933c0c7" alt=""><figcaption></figcaption></figure>

6. Expand **Connect using an API Token**, then copy the JSON snippet and paste it in an editor. Replace `$API_TOKEN` with your token from step 3.
7. Click the **code block** to copy the command to your clipboard.
8. Open your terminal, paste the command, then click **Enter**.
9. 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 via an API token</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 and MCP**, then click **Tokens and MCP Connections**.
3. Click **Create Token**. Name and create a token then copy it and paste it somewhere. You'll need it in the following steps, after you copy another snippet. Tokens are shown **only** at creation time.
4. Return to the **Tokens and MCP Connections** screen.
5. Click **Connect to MCP** > **Claude Desktop**.

<figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2FbSeHsqlZozluaeYIYALO%2Fimage.png?alt=media&amp;token=d191c76a-aa8c-4185-a24c-8d1678f60fef" alt=""><figcaption></figcaption></figure>

6. Expand **Connect using an API Token**, then copy the JSON snippet and paste it in an editor. Replace `$API_TOKEN` with your token from step 3.
7. 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 %}

8. Paste the block from step 6 immediately after the opening `{`, before any existing content.
9. Save the file, then fully quit and relaunch Claude Desktop (on macOS, use **Claude > Quit Claude**, not just the red close button).
10. 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>
11. 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 via an API token</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 and MCP**, then click **Tokens and MCP Connections**.
3. Click **Create Token**. Name and create a token then copy it and paste it somewhere. You'll need it in the following steps, after you copy another snippet. Tokens are shown **only** at creation time.
4. Return to the **Tokens and MCP Connections** screen.
5. Click **Connect to MCP** > **Cursor**

<figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2FLscUAd0QYlu61roZfmvK%2Fimage.png?alt=media&amp;token=7a726af9-7e6c-4c1c-8230-e4f16231a76f" alt=""><figcaption></figcaption></figure>

6. Expand **Connect using an API Token**, then copy the JSON snippet and paste it in an editor. Replace `$API_TOKEN` with your token from step 3.
7. In Cursor, open **Settings > Tools & MCP** and open your `~/.cursor/mcp.json` file.
8. Paste the snippet into the file and save.
9. 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>

<details>

<summary>Connect to ChatGPT via an API token</summary>

Before you begin, make sure you have ChatGPT installed. If you don't, review [ChatGPT's documentation](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt).

1. In Material, from the top toolbar click **Integrations**.
2. Expand **API and MCP**, then click **Tokens and MCP Connections**.
3. Click **Create Token**. Name and create a token then copy it and paste it somewhere. You'll need it in the following steps. Tokens are shown **only** at creation time.
4. Return to the **Tokens and MCP Connections** screen.
5. Click **Connect to MCP** > **ChatGPT**

<figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2Flo97LgEvAndL71GL9dHL%2Fimage.png?alt=media&amp;token=3eddd3b2-186a-4a99-bd8a-31203abeee12" alt=""><figcaption></figcaption></figure>

6. In ChatGPT, navigate to **Settings** > **Security** **and login** then turn on **Developer Mode**.
7. From the sidebar, open **Plugins** then click **+** to add a new plugin. Point it at the Server URL displayed in Material.
8. Set the following values:
   1. **Authentication**: `Access token / API key`
   2. **Header Scheme**: Custom Header
   3. **Header Name**: `x-material-client-secret` and the token value from step 3.
9. Test your connection using [ChatGPT's documentation](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt#test-the-new-app-in-chatgpt).

</details>

<details>

<summary>Connect to Codex via an API token</summary>

Before you begin, make sure you have Codex installed. If you don't, review [Codex's documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli#cli-__codexlocalizedvalueprops__codextranslations-u0016-connect-codex-to-an-mcp-server).

1. In Material, from the top toolbar click **Integrations**.
2. Expand **API and MCP**, then click **Tokens and MCP Connections**.
3. Click **Create Token**. Name and create a token then copy it and paste it somewhere. You'll need it in the following steps. Tokens are shown **only** at creation time.
4. Return to the **Tokens and MCP Connections** screen.
5. Click **Connect to MCP** > **Codex**

<figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2F0zbSKZ5BleVfrEhSMqeo%2Fimage.png?alt=media&amp;token=d95b501a-878a-4397-8dd9-3665ae0fa601" alt=""><figcaption></figcaption></figure>

6. Expand **Connect using an API Token**, then copy the JSON snippet and paste it in an editor. Replace `$API_TOKEN` with your token from step 3.
7. Paste the snippet into `~/.codex/config.toml` (or `.codex/config.toml` for a single project).

</details>

<details>

<summary>Connect to Grok via an API token</summary>

Before you begin, make sure you have [Grok installed](https://docs.x.ai/build/overview). If you don't, review [Grok's documentation](https://docs.x.ai/developers/tools/remote-mcp).

1. In Material, from the top toolbar click **Integrations**.
2. Expand **API and MCP**, then click **Tokens and MCP Connections**.
3. Click **Create Token**. Name and create a token then copy it and paste it somewhere. You'll need it in the following steps. Tokens are shown **only** at creation time.
4. Return to the **Tokens and MCP Connections** screen.
5. Click **Connect to MCP** > **Grok**

<figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2FDBrHi6vtfqYbTQGNZwO7%2Fimage.png?alt=media&amp;token=48c2a740-384f-43d9-b582-33918b349316" alt=""><figcaption></figcaption></figure>

6. Store your token as an environment variable so it stays out of your configuration file. Add the following to your shell profile, then open a new terminal session:

```bash
   export MATERIAL_API_TOKEN="<token from step 3>"
```

7. Open your Grok configuration file at `~/.grok/config.toml`. To scope the connection to a single repository instead, open `.grok/config.toml` in that repository.
8. Add the following, replacing the `url` value with the Server URL displayed in Material:

```toml
   [mcp_servers.material]
   url = "https://your-material-domain/mcp"
   headers = { "x-material-client-secret" = "${MATERIAL_API_TOKEN}" }
```

9. Test your connection by running `grok mcp doctor material`. For more options, see [Grok's documentation](https://docs.x.ai/build/features/mcp-servers).

</details>

<details>

<summary>Connect to other agents via an API token</summary>

1. In Material, from the top toolbar click **Integrations**.
2. Expand **API and MCP**, then click **Tokens and MCP Connections**.
3. Click **Create Token**. Name and create a token then copy it and paste it somewhere. You'll need it in the following steps. Tokens are shown **only** at creation time.
4. Return to the **Tokens and MCP Connections** screen.
5. Click **Connect to MCP**, then expand **Connect using an API token** and copy the **Server URL**.

<figure><img src="https://3441929823-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDXSwW7QZtKgywlqSARjL%2Fuploads%2F6ZAF0hpC5DJZFsjuqxmG%2Fimage.png?alt=media&amp;token=6d52db2b-ad2f-45b6-bc8e-b103ce5746ac" alt=""><figcaption></figcaption></figure>

6. In your MCP client, add a new remote MCP server pointing at the Server URL you copied.
7. Set the following values:
   1. **Header Name**: `x-material-client-secret`
   2. **Header Value**: the token from step 3
8. Test the connection using your MCP client's documentation. Once connected, the client discovers the tools Material exposes and makes them available in your sessions

</details>

### Rolling out to a team

Everyone connects with their own credentials. There's no shared organization-wide token, and each connection is tied to one Material account, whether that person authorizes with OAuth or uses an API token they created themselves.

To roll the MCP server out across a team:

1. Enable the MCP server for your organization, following **One: Enable the MCP Server** above.
2. Confirm your AI provider allows the connection. On Claude Team and Enterprise plans, an Owner has to add Material as a custom connector first. See **Before you begin** above.
3. Have each person connect their own AI client, following **Two: Connect your AI tool** above. Use OAuth unless a client doesn't support it.

{% hint style="info" %}
Connecting doesn't widen anyone's access. Every request is checked against that account's current permissions, so someone sees the same data through their AI client that they'd see in Material, and no more. Each person is also offered only the tools their role allows.
{% endhint %}

***

## Available tools

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

**Issues and messages**

* [**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

**Trusted entities**

* [**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

**Accounts, groups, and roles**

* [**List accounts**](https://docs.material.security/reference/api-v1/accounts): retrieve a filtered list of the accounts synced from Google or Microsoft, narrowed by details like name, email, VIP designation, license, group, or role
* [**Get account**](https://docs.material.security/reference/api-v1/accounts): retrieve a single account, including its VIP designation, licenses, effective settings and where each value comes from, mailbox state, and role assignments
* [**Update account**](https://docs.material.security/reference/api-v1/accounts): change an account's VIP designation, licenses, per-account setting overrides, and role assignments
* [**List groups**](https://docs.material.security/reference/api-v1/groups): retrieve a filtered list of the groups synced from your provider, narrowed by details like name, email, type, or role
* [**Get group**](https://docs.material.security/reference/api-v1/groups): retrieve a single group, including its member count, licenses, the roles it grants its members, and effective settings
* [**List group members**](https://docs.material.security/reference/api-v1/groups): retrieve the accounts that belong to a group
* [**Update group**](https://docs.material.security/reference/api-v1/groups): change a group's licenses, per-group setting overrides, and the roles it grants its members
* [**List roles**](https://docs.material.security/reference/api-v1/roles): review the roles you can assign to accounts and groups on your instance

**OAuth apps**

* [**List OAuth apps**](https://docs.material.security/reference/api-v1/oauth-apps): retrieve a filtered list of the third-party OAuth apps holding token grants in your Google Workspace tenant, narrowed by details like classification or remediation policy
* [**Get OAuth app**](https://docs.material.security/reference/api-v1/oauth-apps): retrieve a single app, including its granted scopes, brand details, classification, and standing remediation policy
* [**List OAuth app accounts**](https://docs.material.security/reference/api-v1/oauth-apps): retrieve the accounts that have granted an app, each with the scopes that account granted
* [**Update OAuth app**](https://docs.material.security/reference/api-v1/oauth-apps): change an app's classification and standing remediation policy
* [**Revoke an account's grant**](https://docs.material.security/reference/api-v1/oauth-apps): revoke one account's grant of an app

{% 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 %}

{% hint style="warning" %}
Assigning roles through **Update account** or **Update group** changes who can do what in Material, and roles granted on a group apply to every member of that group. **Revoke an account's grant** takes effect immediately at the provider and can't be undone: to restore access, the account has to grant the app again. These are security-sensitive, audited actions.
{% 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>

<details>

<summary><strong>Accounts, groups, and roles</strong></summary>

* Show me all the accounts marked as VIPs.
* Which accounts belong to \[group], and which of them have an admin role?
* What roles can I assign on this instance?

</details>

<details>

<summary><strong>OAuth apps</strong></summary>

* Show me the OAuth apps that still have active accounts, with their classification.
* Which accounts granted \[app], and what scopes did each one grant?
* Summarize what \[app] can access and whether anything looks concerning.

</details>

## Rate limiting

The Material MCP server is rate limited separately from the v1 API. If you reach the limit, the server returns HTTP `429` with a `Retry-After` header giving the number of seconds to wait, along with a JSON-RPC error whose code is also `429`. Your AI client can use these to recognize the limit, wait, and retry on its own, so requests resume after a short wait.

***

## Troubleshooting

<details>

<summary><strong>You can't add Material as a connector in Claude</strong></summary>

If the **Add** button is missing under **Organization settings** > **Connectors**, custom connectors aren't enabled for your Claude organization. On Team and Enterprise plans only an Owner can add one.

Ask an Owner to add Material for you. See [**Before you begin**](#before-you-begin) above for a request you can send them, and for a Claude Desktop route you can use in the meantime.

</details>

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.material.security/reference/material-mcp-server.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.