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!

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

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.

Ask your Claude organization Owner to add Material

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.

Working in Claude Desktop before a connector is added

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.

When you're ready, follow Connect to Claude Desktop via an API token below.

How to connect

One: Enable the MCP Server

To enable the MCP server, you need a Super Admin, Tenant Admin, Global Settings Admin, or Settings Admin role.

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.

   

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.

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.

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.

Connect to Claude Code via an API token in the terminal

Before you begin, make sure you have Claude Code installed. If you don't, review Claude Code's documentation.

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

1. 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.
2. Click the code block to copy the command to your clipboard.
3. Open your terminal, paste the command, then click Enter.
4. 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.

Connect to Claude Desktop via an API token

Before you begin, install Node.js (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.

1. 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.
2. 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

You can also ask Claude Code to assist you in updating this file.

1. Paste the block from step 6 immediately after the opening {, before any existing content.
2. Save the file, then fully quit and relaunch Claude Desktop (on macOS, use Claude > Quit Claude, not just the red close button).
3. 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.

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

   

Need to disconnect? See How to disconnect the Material MCP.

Connect to Cursor via an API token

Before you begin, make sure you have Cursor installed. If you don't, review Cursor's documentation.

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

1. 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.
2. In Cursor, open Settings > Tools & MCP and open your ~/.cursor/mcp.json file.
3. Paste the snippet into the file and save.
4. 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.

Connect to ChatGPT via an API token

Before you begin, make sure you have ChatGPT installed. If you don't, review ChatGPT's documentation.

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

1. In ChatGPT, navigate to Settings > Security and login then turn on Developer Mode.
2. From the sidebar, open Plugins then click + to add a new plugin. Point it at the Server URL displayed in Material.
3. 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.
4. Test your connection using ChatGPT's documentation.

Connect to Codex via an API token

Before you begin, make sure you have Codex installed. If you don't, review Codex's documentation.

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

1. 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.
2. Paste the snippet into ~/.codex/config.toml (or .codex/config.toml for a single project).

Connect to Grok via an API token

Before you begin, make sure you have Grok installed. If you don't, review Grok's documentation.

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

1. 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:

   export MATERIAL_API_TOKEN="<token from step 3>"

1. 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.
2. Add the following, replacing the url value with the Server URL displayed in Material:

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

1. Test your connection by running grok mcp doctor material. For more options, see Grok's documentation.

Connect to other agents via an API token

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.

1. In your MCP client, add a new remote MCP server pointing at the Server URL you copied.
2. Set the following values:

   1. Header Name: x-material-client-secret
   2. Header Value: the token from step 3
3. 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

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.

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.

---

Available tools

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

Issues and messages

• List issues: retrieve a filtered list of issues, such as all open high-severity issues or issues from a specific sender
• Get issue: retrieve the full details of a single issue
• Update issue: 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: retrieve the full details of a single email message associated with an issue

Trusted entities

• List trusted entities: review the domains, email addresses, and IP addresses or CIDR ranges your instance trusts
• Get trusted entity: retrieve a single trusted entity and its settings
• Create trusted entity: add a new trusted entity
• Update trusted entity: change a trusted entity's settings, such as disabling it
• Delete trusted entity: remove a trusted entity you've added

Accounts, groups, and roles

• List 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: retrieve a single account, including its VIP designation, licenses, effective settings and where each value comes from, mailbox state, and role assignments
• Update account: change an account's VIP designation, licenses, per-account setting overrides, and role assignments
• List groups: retrieve a filtered list of the groups synced from your provider, narrowed by details like name, email, type, or role
• Get group: retrieve a single group, including its member count, licenses, the roles it grants its members, and effective settings
• List group members: retrieve the accounts that belong to a group
• Update group: change a group's licenses, per-group setting overrides, and the roles it grants its members
• List roles: review the roles you can assign to accounts and groups on your instance

OAuth apps

• List 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: retrieve a single app, including its granted scopes, brand details, classification, and standing remediation policy
• List OAuth app accounts: retrieve the accounts that have granted an app, each with the scopes that account granted
• Update OAuth app: change an app's classification and standing remediation policy
• Revoke an account's grant: revoke one account's grant of an app

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.

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.

Example prompts to get started

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

Example in Claude Desktop

Example in Claude Code via the terminal

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

Incident triage

• 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

Filtering and prioritizing

• 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

User history

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

Deep dive

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.

Remediation

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

Trusted entity management

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

Accounts, groups, and roles

• 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?

OAuth apps

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

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

You can't add Material as a connector in Claude

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 above for a request you can send them, and for a Claude Desktop route you can use in the meantime.

Authentication errors

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

Connection not working

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

Disconnect the Material MCP

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.

Remediation behaving unexpectedly

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

Slow or no responses

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.

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.