Skip to content

Commit f1b5354

Browse files
vkumbharajlearner17
vkumbha
and
rajlearner17
authored
Add guide - Guardrails MCP. Closes #340 (#342)
Co-authored-by: raj <raj@turbot.com>
1 parent 77a205c commit f1b5354

File tree

3 files changed

+169
-0
lines changed

3 files changed

+169
-0
lines changed

‎docs/guides/using-guardrails/ai-tools/index.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
---
2+
title: AI Tools (MCP)
3+
sidebar_label: AI Tools (MCP)
4+
---
5+
6+
# Configure Guardrails MCP Server
7+
8+
In this guide, you will:
9+
10+
- Install and configure the Guardrails [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server to enable AI assistant integration.
11+
- Connect your AI assistant to interact with your Guardrails environment.
12+
- Use natural language to explore and manage your cloud infrastructure.
13+
14+
The [Guardrails](https://turbot.com/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:
15+
16+
- Querying and analyzing cloud resources using GraphQL
17+
- Listing and filtering resource, control, and policy types
18+
- Executing controls and reviewing compliance
19+
- Exploring GraphQL schemas for custom queries
20+
- Processing templates using Nunjucks for dynamic configurations
21+
22+
## Prerequisites
23+
24+
Before setting up Guardrails MCP, you need:
25+
26+
- Node.js v20 or higher installed on your system
27+
- A Turbot Guardrails API key with appropriate permissions
28+
- At minimum, Turbot/ReadOnly permission to run GraphQL queries
29+
- Turbot/Operator permission if you need to run controls or modify policies
30+
- Your Guardrails workspace URL (e.g., `https://your-workspace.cloud.turbot.com`)
31+
- An AI assistant that supports MCP (Claude Desktop, Cursor, etc.)
32+
33+
To generate a Guardrails API key, see [Guardrails API Access Keys](https://turbot.com/guardrails/docs/guides/using-guardrails/iam/access-keys#generate-a-new-guardrails-api-access-key).
34+
35+
## Step 1: Install MCP Server
36+
37+
Guardrails MCP is installed using npx, which runs the published npm package without requiring manual installation.
38+
39+
The npx approach is used in the configuration examples throughout this guide and provides the simplest way to get started with Guardrails MCP.
40+
41+
No additional installation steps are required as the configuration will automatically handle this for you.
42+
43+
> [!NOTE]
44+
> If you need to customize the MCP server functionality, you can clone and modify the code from the [Guardrails MCP GitHub repo](https://github.com/turbot/guardrails-mcp). However, for most use cases, the npx installation method described above is recommended.
45+
46+
## Step 2: Configure MCP Server
47+
48+
Set up a configuration file for your AI assistant with the following structure:
49+
50+
```json
51+
{
52+
"mcpServers": {
53+
"turbot-guardrails": {
54+
"command": "npx",
55+
"args": ["-y", "@turbot/guardrails-mcp"],
56+
"env": {
57+
"TURBOT_GRAPHQL_ENDPOINT": "https://your-workspace.cloud.turbot.com/api/latest/graphql",
58+
"TURBOT_ACCESS_KEY_ID": "your-access-key-id",
59+
"TURBOT_SECRET_ACCESS_KEY": "your-secret-access-key"
60+
}
61+
}
62+
}
63+
}
64+
```
65+
66+
### Configuration Locations
67+
68+
Place the configuration file in the correct location based on your AI assistant:
69+
70+
| Assistant | Configuration File Location | Setup Guide |
71+
| ------------------------ | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
72+
| Claude Desktop (Windows) | `%APPDATA%\Claude Desktop\claude_desktop_config.json` |
73+
| Claude Desktop (macOS) | `~/Library/Application Support/Claude Desktop/claude_desktop_config.json` | [Claude Desktop MCP Guide →](https://modelcontextprotocol.io/quickstart/user) |
74+
| Claude Desktop (Linux) | `~/.config/Claude Desktop/claude_desktop_config.json` |
75+
| Cursor (Per-user) | `~/.cursor/mcp.json` |
76+
| Cursor (Per-workspace) | `.cursor/mcp.json` in the workspace directory | [Cursor MCP Guide →](https://docs.cursor.com/context/model-context-protocol) |
77+
78+
### Environment Variables
79+
80+
The configuration requires these environment variables:
81+
82+
| Variable | Description |
83+
| -------------------------- | ---------------------------------------- |
84+
| `TURBOT_GRAPHQL_ENDPOINT` | Your Guardrails GraphQL API endpoint URL |
85+
| `TURBOT_ACCESS_KEY_ID` | Your Guardrails API access key ID |
86+
| `TURBOT_SECRET_ACCESS_KEY` | Your Guardrails API secret access key |
87+
88+
## Step 3: Configure AI Assistant
89+
90+
### Claude Desktop
91+
92+
1. Create or edit the Claude Desktop configuration file in the appropriate location for your OS.
93+
2. Add the Guardrails MCP server configuration (as shown above).
94+
3. Save the file and restart Claude Desktop.
95+
96+
### Cursor
97+
98+
For Cursor, you have two options for configuration:
99+
100+
#### Per-user Configuration (applies to all workspaces)
101+
102+
1. Create or edit `~/.cursor/mcp.json`
103+
2. Add the Guardrails MCP server configuration
104+
3. Save the file and restart Cursor
105+
106+
#### Per-workspace Configuration (applies only to the current workspace)
107+
108+
1. Create or edit `.cursor/mcp.json` in your workspace directory
109+
2. Add the Guardrails MCP server configuration
110+
3. Save the file and restart Cursor
111+
112+
> [!NOTE]
113+
> Per-workspace configuration takes precedence over per-user configuration when both exist.
114+
115+
## Step 4: Query Guardrails
116+
117+
Start by asking about your Guardrails environment, for example:
118+
119+
```
120+
Which Turbot Environment (TE) version is currently running in my workspace?
121+
```
122+
123+
Simple, specific questions work well:
124+
125+
```
126+
Show me all S3 buckets created in the last week
127+
```
128+
129+
Generate compliance and security reports:
130+
131+
```
132+
List all EC2 instances that are non-compliant with our tagging standards
133+
```
134+
135+
Explore policy and control types:
136+
137+
```
138+
Show me all policy types related to encryption
139+
List all control types for S3 buckets
140+
```
141+
142+
Dive into resource details:
143+
144+
```
145+
Show details for resource ID 1234567890
146+
```
147+
148+
> [!TIP]
149+
> - Be specific about which resources, controls, or policies you want to analyze
150+
> - Use filters for categories, titles, or tags
151+
> - Start with simple queries before adding complex conditions
152+
> - Use natural language – the LLM will handle the GraphQL translation
153+
154+
<!-- ## Next Steps
155+
156+
- Explore the [Turbot Guardrails documentation](https://turbot.com/guardrails/docs) for more information about Guardrails concepts
157+
- Check out the [Guardrails Hub](https://hub.guardrails.turbot.com) for available policy packs
158+
- Try the example prompts in the [Example Usage](#example-usage) section below -->
159+
160+
## Troubleshooting
161+
162+
| Issue | Description | Guide |
163+
| --------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
164+
| Authentication Errors | API key is incorrect or lacks necessary permissions | [Guardrails Access Keys](https://turbot.com/guardrails/docs/guides/using-guardrails/iam/access-keys) |
165+
| Connection Issues | Guardrails endpoint URL is incorrect or network connectivity problems | Check your network configuration and endpoint URL format |
166+
| API Errors | GraphQL error messages in server logs | Review server logs and ensure your API key has required permissions |
167+
| Further Assistance | If you continue to encounter issues | [Open Support Ticket](https://support.turbot.com) |

‎docs/guides/using-guardrails/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ This section provides how-to guides for common tasks.
88

99
| Section | Description
1010
| - | -
11+
| [AI Tools](guides/using-guardrails/ai-tools) | Learn how to use different AI integration tools and prompts
1112
| [Console](guides/console) | Navigate the Guardrails Console user interface
1213
| [GraphQL](guides/graphql) | Tips and Tricks for GraphQL
1314
| [IAM](guides/iam) | Manage directories, users, and permissions

‎docs/sidebar.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -295,6 +295,7 @@
295295
"id": "using-guardrails",
296296
"link": "guides/using-guardrails",
297297
"items": [
298+
"guides/using-guardrails/ai-tools",
298299
{
299300
"type": "category",
300301
"id": "console",

0 commit comments

Comments
 (0)