Connecting an AI Agent to Addigy with the MCP Server

The Addigy MCP server lets any AI agent that supports the Model Context Protocol (MCP) manage your Addigy organization conversationally, no hand-written API calls required. Once connected, you can ask your agent things like "Build an end of quarter report for my org" or "show me devices out of compliance" and it runs the right Addigy API calls for you. Currently in Beta, email product@addigy.com for access.

• Broad coverage – Roughly 240 tools spanning devices, policies, compliance benchmarks, MDM profiles, alerts, and more
• Nothing to install or run – The server is hosted at https://mcp.addigy.com/mcp and uses MCP Streamable HTTP; there is no local component
• Scoped by your API key – The agent authenticates with an Addigy API key and can never do more than that key's permissions allow
• Fast setup – One config entry plus a restart of your agent, about 5 minutes

How It Works

1. You create an Addigy API key scoped to the permissions you want the agent to have.
2. You register the Addigy MCP server in your AI client's MCP configuration, passing the key as an x-api-key header.
3. After a restart, your agent discovers the Addigy tools and can call them on your behalf in conversation.
4. Operations that change or delete data require your confirmation first, via MCP's Elicitation feature.

Before You Begin

• An MCP-capable AI agent: Any client that supports remote MCP servers over Streamable HTTP with custom headers works. Claude Code, Cursor, VS Code, and Claude Desktop are covered below; most other MCP clients follow the same pattern.
• An Addigy API key for the organization you want to manage. Create one in the Addigy dashboard under Account → Integrations. Give the key only the permissions that match what you plan to do (e.g., View Devices, Edit Policy Benchmarks), the agent can never do more than the key allows.
• For Claude Desktop only: Node.js 18 or newer, since its setup runs a small bridge via npx. Check with node --version.

⚠️ Security Note: Treat any config file containing a real API key as a secret. Do not commit it to a shared repository — add it to .gitignore, or use your client's environment-variable substitution if it supports one.

Step 1: Add the Server to Your Agent

Purpose: Register the Addigy MCP server in your client's configuration so the agent can discover and call Addigy tools.

Every MCP client needs the same three pieces of information — only the config file location differs:

Claude Code

Add to .mcp.json at your project root (create the file if it doesn't exist):

{
  "mcpServers": {
    "addigy": {
      "type": "http",
      "url": "https://mcp.addigy.com/mcp",
      "headers": {
        "x-api-key": "YOUR_ADDIGY_API_KEY"
      }
    }
  }
}

Cursor

Add the same block to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "addigy": {
      "url": "https://mcp.addigy.com/mcp",
      "headers": {
        "x-api-key": "YOUR_ADDIGY_API_KEY"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "addigy": {
      "type": "http",
      "url": "https://mcp.addigy.com/mcp",
      "headers": {
        "x-api-key": "YOUR_ADDIGY_API_KEY"
      }
    }
  }
}

Claude Desktop

Claude Desktop needs a slightly different setup. Its built-in Connectors UI (Settings → Connectors → Add custom connector) only supports remote servers that use OAuth — it provides a URL field but no place to add the x-api-key header Addigy requires, so pasting the URL there will not authenticate. Instead, configure the server in Claude Desktop's config file and let the mcp-remote bridge carry the header for you.

1. Install Node.js (18 or newer) if you don't have it — the bridge runs via npx. Check with node --version.
2. Open the config file: in Claude Desktop go to Settings → Developer → Edit Config, or open the file directly:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Add the addigy server below (merge into any existing mcpServers — don't overwrite other servers), then save and fully quit and reopen Claude Desktop.

{
  "mcpServers": {
    "addigy": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.addigy.com/mcp",
        "--header", "x-api-key:${ADDIGY_API_KEY}"
      ],
      "env": { "ADDIGY_API_KEY": "YOUR_ADDIGY_API_KEY" }
    }
  }
}

Why the ${ADDIGY_API_KEY} pattern? mcp-remote mis-parses a --header value that contains a space, so pass the key with no space (x-api-key:${ADDIGY_API_KEY}) and let mcp-remote substitute it from the env block. This also keeps the raw key out of the visible arguments.

macOS with a Node version manager (nvm, asdf, Volta)? Claude Desktop launches as a GUI app and won't inherit your shell's PATH, so a bare "command": "npx" can fail with "npx not found." If it does, replace "npx" with the absolute path — find it by running which npx in your terminal (e.g., /Users/you/.nvm/versions/node/vXX/bin/npx).

Other MCP Clients

Any client that can register a remote MCP server over Streamable HTTP with a custom header will work — supply the URL and the x-api-key header wherever the client configures remote servers. If your client only supports OAuth-based remote connectors and can't send custom headers, use one of the clients above instead. For full access to operations that change data, your client must also support Elicitation — see the Notes section.

Most agents establish MCP connections at startup — after adding or editing the server config, restart your agent or the Addigy tools won't appear in the session.

Step 2: Verify It Works

Purpose: Confirm the server is connected and your API key authenticates before you rely on the integration.

1. Check the connection status in your client. Each client shows connected MCP servers in its own way — in Claude Code, run claude mcp list in the terminal and look for addigy: … (HTTP) - Connected; in Cursor and VS Code, check the MCP section of settings. A "failed to connect" result usually means a problem with the API key — see Troubleshooting below.
2. Confirm your identity. Ask your agent to call the WhoAmI tool. A healthy response returns the key's name and your organization_id — that single call confirms your key is connected and working. (A key's permissions come from a separate call.)
3. Try a read-only call. For example, "list the policies in my Addigy org" or "show my devices." Always start with read-only calls before anything that changes data.

Shortcut: Let Your Agent Set Itself Up

If your agent can edit files and run commands (Claude Code, Cursor, and similar), you can hand it the whole job. Paste the prompt below, replacing the placeholders first:

Set up the Addigy MCP server for this project.

1. Add an MCP server named "addigy" to this client's MCP config:
   - transport: http (MCP Streamable HTTP)
   - url: https://mcp.addigy.com/mcp
   - header x-api-key: YOUR_ADDIGY_API_KEY

   Preserve any MCP servers already configured — don't overwrite them.

2. Verify the server is reachable and my key works BEFORE telling me it's done: run the MCP
   initialize handshake against the URL with my key (a curl POST is fine), then the full
   initialize -> notifications/initialized -> tools/list sequence. Report exactly what came back.

3. Interpret the result for me:
   - If initialize succeeds but tool calls return "could not authenticate x-api-key" -> tell me
     it may be a transient hiccup or a key-permissions issue (suggest a retry, then checking the
     key under Account -> Integrations).
   - If it all works -> confirm, and remind me to restart the agent so the Addigy tools load.

4. After I restart, call the WhoAmI tool and show me my org ID and key name to
   confirm the connection end-to-end.

Don't run any Addigy tool that changes data during setup — read-only checks only.

Troubleshooting

To isolate whether a problem is on your side or the server's, reproduce the handshake manually with curl — this takes your agent out of the picture entirely. Replace KEY with your API key:

KEY="YOUR_ADDIGY_API_KEY"
curl -sS -X POST https://mcp.addigy.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: $KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}'

Notes

• Destructive operations require Elicitation. Tools that change or delete data ask your agent to confirm the action first, using MCP's Elicitation feature. If your client doesn't support Elicitation, the Addigy server denies those requests — read-only calls are unaffected. Claude Code supports Elicitation; check your client's MCP feature support before relying on write operations.
• The agent's access is always bounded by the API key's permissions. To change what the agent can do, edit the key's permissions in Account → Integrations.
• Most MCP clients only read their config at startup — restart the agent after any config change.
• API keys in config files are secrets: keep them out of shared repositories and use environment-variable substitution where your client supports it.