Install Guardrails MCP

Install the Guardrails' MCP Server for AI Assisted Development

In this guide, you will:

• Install and configure the Guardrails Model Context Protocol (MCP) server to enable AI assistant integration.
• Connect your AI assistant to interact with your Guardrails environment.
• Use natural language to explore and manage your cloud infrastructure.

The Guardrails Model Context Protocol (MCP) server enables AI assistants to interact with your Guardrails environment through natural language queries. By connecting AI assistants to your Guardrails data, you can:

• Querying and analyzing cloud resources using GraphQL
• Listing and filtering resource, control, and policy types
• Executing controls and reviewing compliance
• Exploring GraphQL schemas for custom queries
• Processing templates using Nunjucks for dynamic configurations

Prerequisites

Before setting up Guardrails MCP, you need:

• Node.js v20 or higher installed on your system
• A Turbot Guardrails API key with appropriate permissions
• At minimum, Turbot/ReadOnly permission to run GraphQL queries
• Turbot/Operator permission if you need to run controls or modify policies
• Your Guardrails workspace URL (e.g., https://your-workspace.cloud.turbot.com)
• An AI assistant that supports MCP (Claude Desktop, Cursor, etc.)

To generate a Guardrails API key, see Guardrails API Access Keys.

Step 1: Install MCP Server

Guardrails MCP is installed using npx, which runs the published npm package without requiring manual installation.

The npx approach is used in the configuration examples throughout this guide and provides the simplest way to get started with Guardrails MCP.

No additional installation steps are required as the configuration will automatically handle this for you.

[!NOTE] If you need to customize the MCP server functionality, you can clone and modify the code from the Guardrails MCP GitHub repo. However, for most use cases, the npx installation method described above is recommended.

Step 2: Configure MCP Server

Set up a configuration file for your AI assistant with the following structure:

{
  "mcpServers": {
    "turbot-guardrails": {
      "command": "npx",
      "args": ["-y", "@turbot/guardrails-mcp"],
      "env": {
        "TURBOT_GRAPHQL_ENDPOINT": "https://your-workspace.cloud.turbot.com/api/latest/graphql",
        "TURBOT_ACCESS_KEY_ID": "your-access-key-id",
        "TURBOT_SECRET_ACCESS_KEY": "your-secret-access-key"
      }
    }
  }
}

Configuration Locations

Place the configuration file in the correct location based on your AI assistant:

Environment Variables

The configuration requires these environment variables:

Step 3: Configure AI Assistant

Claude Desktop

1. Create or edit the Claude Desktop configuration file in the appropriate location for your OS.
2. Add the Guardrails MCP server configuration (as shown above).
3. Save the file and restart Claude Desktop.

Cursor

For Cursor, you have two options for configuration:

Per-user Configuration (applies to all workspaces)

1. Create or edit ~/.cursor/mcp.json
2. Add the Guardrails MCP server configuration
3. Save the file and restart Cursor

Per-workspace Configuration (applies only to the current workspace)

1. Create or edit .cursor/mcp.json in your workspace directory
2. Add the Guardrails MCP server configuration
3. Save the file and restart Cursor

[!NOTE] Per-workspace configuration takes precedence over per-user configuration when both exist.

Step 4: Query Guardrails

Start by asking about your Guardrails environment, for example:

Which Turbot Environment (TE) version is currently running in my workspace?

Simple, specific questions work well:

Show me all S3 buckets created in the last week

Generate compliance and security reports:

List all EC2 instances that are non-compliant with our tagging standards

Explore policy and control types:

Show me all policy types related to encryption
List all control types for S3 buckets

Dive into resource details:

Show details for resource ID 1234567890

[!TIP]

• Be specific about which resources, controls, or policies you want to analyze
• Use filters for categories, titles, or tags
• Start with simple queries before adding complex conditions
• Use natural language – the LLM will handle the GraphQL translation

Troubleshooting