Quickstart: Claude

Claude reaches Guardyx over MCP. Which way you connect depends on where you use Claude:

All three take about five minutes. You need a Guardyx workspace.

1. In the Guardyx portal, open My Agents and choose Connect new agent.
2. Under Which app will you chat with?, pick Claude Desktop or Claude.ai (web). For Claude Code, pick Custom MCP (Another app that supports custom connections).
3. Choose the apps it should use and what it may do, then connect your accounts.
4. On the last step, leave the page open. It shows what to paste into Claude and the connection status, which turns to Connected once Claude reaches Guardyx.

Claude Desktop runs the mcp-remote bridge, which forwards its local MCP calls to Guardyx over HTTPS.

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

2. Paste the snippet from the portal. If the file already has other servers, add the guardyx entry under mcpServers and keep the others.

   {
     "mcpServers": {
       "guardyx": {
         "command": "npx",
         "args": [
           "-y", "mcp-remote",
           "https://app.guardyx.ai/v1/mcp",
           "--header", "X-API-Key:gx_live_YOUR_KEY"
         ]
       }
     }
   }

3. Fully quit Claude Desktop and reopen it. Closing the window isn’t enough, because Claude Desktop loads MCP servers only at startup.

4. Open the tools menu in the composer. guardyx appears there.

Claude.ai connects straight to Guardyx over HTTPS and signs in with OAuth 2.1, so there’s no config file and no API key. You give it a client ID and secret, and then you approve the connection on a Guardyx consent screen. That approval is what grants access, and it ties the connection to one agent.

1. From the portal’s last step, copy the Server URL, Client ID, and Client secret.
2. In Claude.ai, open Settings → Connectors → Add custom connector.
3. Set the URL to https://app.guardyx.ai/v1/mcp.
4. Open Advanced settings and paste the Client ID and Client secret.
5. Choose to connect. Claude.ai sends you to Guardyx: sign in, pick your agent, check the tools it grants, and choose Allow.

Registering the connector doesn’t connect it. If you stop before Allow, the connector looks set up in Claude.ai, but every call fails.

The consent expires after 90 days by default. When it does, Claude.ai sends you through Allow again. To cut the connection sooner, open the agent in Guardyx and revoke it under Authentication.

Claude Code uses the same mcp-remote bridge as Claude Desktop. Keep the key in an environment variable (add the export to your shell profile), then register the server from your project root:

export GUARDYX_API_KEY=gx_live_YOUR_KEY
claude mcp add -s project guardyx -- \
  npx -y mcp-remote https://app.guardyx.ai/v1/mcp --header 'X-API-Key:${GUARDYX_API_KEY}'

The single quotes keep ${GUARDYX_API_KEY} as written, so the config holds the variable’s name, not your key. Claude Code fills it in each time it starts the server.

-s project writes the entry to .mcp.json at the repo root. Use -s user instead to register it for all your projects. Leaving the flag out registers it for this project only, without writing .mcp.json. Run claude mcp list to confirm that guardyx connects.

You can commit that .mcp.json: it has no key in it. Each teammate exports their own GUARDYX_API_KEY, so each one stays a separate agent in the trace.

1. Look at the portal’s last step. Its status changes to Connected.

2. Ask Claude to do something with one of your connected apps, for example “What’s on my calendar today?”

   If Claude answers that no calendar is connected, it didn’t look in Guardyx. Your apps sit behind Guardyx’s search tool, so Claude doesn’t see them on its own. Name Guardyx in the request: “Use Guardyx to check what’s on my calendar today.”

3. Open Runs in Guardyx. The call is there, with its inputs, the policy decision, and the outcome.

4. Ask for something your policy holds for review. Claude waits while the request appears in Approvals. If you don’t decide within about 25 seconds, Claude gets a retry message, and the same call picks up your decision when it is retried.

Claude’s tool list shows three tools: guardyx_search_tools, guardyx_describe_tool, and guardyx_execute_tool. That is expected. Claude searches your toolbox through them, so the list stays short however many apps you connect.

Every AI action passes through Guardyx. Each tool call Claude makes is checked against your policy, sensitive ones wait for your approval, and each request, decision, and outcome is recorded in a tamper-evident run trace.