guardrails

Turbot Guardrails MCP bridges AI assistants with your Guardrails environment, enabling natural language exploration, analysis, and automation over your cloud estate. With this MCP server, you can run read-only GraphQL queries, list resources, controls, policies, and types, render dynamic configurations with Nunjucks templates, and execute Guardrails controls directly from conversational prompts. The available tools include core query and template rendering (guardrails_query, guardrails_query_runnable, guardrails_query_runnable_introspection, guardrails_process_template) as well as resource, control, and policy operations (list, show, run for controls; list and show for resources, policies, and types).

To use the MCP, configure your AI assistant with the provided mcpServers entry, supply your Guardrails GraphQL endpoint and credentials via environment variables, and then issue natural language prompts that map to the supported Guardrails operations. For example, ask to list all policy types, render a configuration template, run a specific control by ID, or introspect a runnable type to understand its queries. The MCP will translate your questions into GraphQL queries and return structured results suitable for further analysis or automation.

Prerequisites:

• Node.js v20 or higher
• A Turbot Guardrails API access key with appropriate permissions
• The endpoint URL for your Guardrails workspace

Install and configure:

1. Clone the repository (or use the MCP server package if provided):

# Optional if you’re using the source repository
git clone https://github.com/turbot/guardrails-mcp.git
cd guardrails-mcp

2. Install dependencies:

npm install

3. Create a .env file (or use the example structure in the README) with your credentials and endpoint, or provide them directly in the MCP config:

cp .env.example .env
# Edit .env with your API credentials and endpoint

4. Build the project (if required by your setup):

npm run build

5. Run the MCP server using the configuration example from the README (or your own environment):

# If using the provided mcp_config JSON, place it in your AI assistant's config

6. For development with auto-recompilation, you can use:

npm run watch

7. If you want to test locally with Claude Desktop, update your assistant config to point to your local development server as shown in the README.

Note: Ensure your environment variables (TURBOT_GRAPHQL_ENDPOINT, TURBOT_ACCESS_KEY_ID, TURBOT_SECRET_ACCESS_KEY) are securely stored and not committed to source control.

Tips and troubleshooting:

• Authentication Errors: Verify your Guardrails API key and permissions, and confirm the TURBOT_GRAPHQL_ENDPOINT is correct.
• Endpoint Connectivity: Ensure network access to the Guardrails GraphQL endpoint from the environment running the MCP.
• Environment Variables: Keep credentials secure; consider using a secret manager or environment variable injection in your deployment.
• CLI vs UI: The MCP is designed to enable natural language queries via your AI assistant; you will interact with it through prompts rather than direct CLI commands.
• GraphQL Introspection: Use guardrails_query_runnable_introspection to understand runnable schemas before composing complex queries.
• Templates: When using guardrails_process_template, ensure your input data aligns with the expected template context for successful rendering.
• Debugging: If results are empty or error messages appear, check server logs, validate the GraphQL query structure, and confirm that the endpoint and credentials are up to date.