Connect your AI Agents to Microsoft Graph Security in minutes
Available tools
list_alerts
List security alerts (alertsv2), correlated into incidents. Filter by status, classification, determination, severity, serviceSource, assignedTo, or date range - filtering is server-side, so prefer it over paging every alert. Evidence is omitted per item unless includeevidence=true; use get_alert for one alert's full evidence.
get_alert
Get a single security alert by ID, including its full evidence. Use list_alerts to find valid alert IDs.
update_alert
Update a security alert's status, classification, determination, assignment, or custom details. Only fields you provide are changed. Use listalerts or getalert to find valid alert IDs. Note: unassigning (empty string) may silently not persist - Graph can ignore null on assignedTo despite documenting it. Check this response's assignedTo field to confirm.
run_hunting_query
Run a KQL advanced hunting query against the Microsoft 365 Defender schema (device, email, identity, cloud app tables). Explores 30 days of data by default (override with timespan), returns up to 100000 rows, times out after 3 minutes. A 429 means the tenant's hunting CPU quota was hit for this 15-minute cycle - wait before retrying.
list_incidents
List security incidents - groups of correlated alerts from the same attack. Filter by status/classification/determination/severity/assignedTo/date range - filtering is done server-side, so prefer it over paging through every incident. Set expandalerts=true to include each incident's correlated alerts inline. Use cursor from pageinfo for the next page.
get_incident
Get a single security incident by ID. Set expandalerts=true to include its correlated alerts inline. Use listincidents to find valid incident IDs.
update_incident
Update a security incident's status, classification, determination, severity, name, description, summary, custom tags, assignment, or resolving comment. Only fields you provide are changed. Use listincidents or getincident to find valid incident IDs. Note: unassigning may silently not persist - Graph can ignore null on assignedTo despite documenting it. Check this response's assignedTo.
list_secure_scores
List Microsoft Secure Score snapshots for the tenant over time. Items omit the per-control breakdown, tenant-comparison scores, and vendor info (large at scale); use getsecurescore for a snapshot's full detail. filter is a raw OData $filter expression - Graph doesn't document filterable properties, try e.g. azureTenantId. Use cursor from page_info for the next page.
get_secure_score
Get a single Secure Score snapshot by ID, including its per-control score breakdown. Use listsecurescores to find valid secure score IDs.
list_secure_score_control_profiles
List Secure Score control profiles - the security controls behind the tenant's Secure Score, with current state (Default/Ignored/ThirdParty/Reviewed). Items omit remediation text (large across many controls); use getsecurescorecontrolprofile for a control's full remediation guidance. filter is a raw OData $filter expression - Graph doesn't document filterable properties here, try ones seen on a returned object (e.g. controlCategory). Use cursor for the next page.
get_secure_score_control_profile
Get a single Secure Score control profile by ID. Use listsecurescorecontrolprofiles to find valid profile IDs. Read its vendorInformation before calling updatesecurescorecontrolprofile, which requires those exact values.
update_secure_score_control_profile
Update a Secure Score control profile, typically to mark it Ignored/ThirdParty/Reviewed via controlstateupdates. vendorprovider and vendorname are required by the Graph API - call getsecurescorecontrolprofile first and pass back its current vendorInformation provider/vendor values (commonly 'SecureScore'/'Microsoft'). Use listsecurescorecontrolprofiles to find valid profile IDs.
validate_credential
Validate Microsoft Graph Security credentials by calling GET /me on Microsoft Graph.
How to set up Merge Agent Handler
In an mcp.json file, add the configuration below, and restart Cursor.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5 "headers": {
6 "Authorization": "Bearer yMt*****"
7 }
8 }
9 }
10}
11Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.
Make sure Claude is using the Node v20+.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "yMt*****"
14 }
15 }
16 }
17}Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.
Learn more in the official documentation ↗
1{
2 "mcpServers": {
3 "agent-handler": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "mcp-remote@latest",
8 "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9 "--header",
10 "Authorization: Bearer ${AUTH_TOKEN}"
11 ],
12 "env": {
13 "AUTH_TOKEN": "<ah-production-access-key>"
14 }
15 }
16 }
17 }In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".
You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.
Learn more in the official documentation ↗
1{
2 "inputs": [
3 {
4 "type": "promptString",
5 "id": "agent-handler-auth",
6 "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7 "password": true
8 }
9 ],
10 "servers": {
11 "agent-handler": {
12 "type": "stdio",
13 "command": "npx",
14 "args": [
15 "-y",
16 "mcp-remote@latest",
17 "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18 "--header",
19 "Authorization: Bearer ${input:agent-handler-auth}"
20 ]
21 }
22 }
23}FAQs on using Merge's Microsoft Graph Security MCP server
FAQs on using Merge's Microsoft Graph Security MCP server
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
