# Hasura MCP

> Hasura connects your GraphQL engine directly to your AI agent, letting you manage complex database operations through natural language. Use this MCP to run queries, check metadata consistency, analyze SQL performance plans, and trigger database dumps without leaving your chat interface.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** graphql, hasura, postgres, api-engine, sql-analysis

## Description

This connection lets you talk to your backend database like it's a simple API endpoint. You can execute full GraphQL mutations or read complex data structures just by describing what you need. Need to know if the schema is consistent? Call `check_health`. Want to optimize a slow query? Use `explain_graphql` to see exactly where Postgres is struggling. It’s also useful for maintenance; trigger a quick dump of your database tables using `pg_dump`, or manage permissions by executing metadata operations. Because Vinkius hosts this MCP, you get access to all these critical developer functions from one single connection point, no matter what AI client you prefer.

## Tools

### check_health
Monitors the overall status of your Hasura system, optionally verifying metadata consistency.

### execute_graphql
Runs any complex GraphQL query or mutation against your data source.

### execute_metadata
Allows you to perform operations directly on the Hasura metadata API for schema management.

### explain_graphql
Analyzes a GraphQL query and returns the underlying SQL execution plan, highlighting performance issues.

### get_config
Retrieves the current operational configuration details for your Hasura instance.

### get_version
Fetches specific version and type information about the running Hasura service.

### pg_dump
Executes a full database dump of a connected Postgres source for schema archiving or transfer.

## Prompt Examples

**Prompt:** 
```
Run a GraphQL query to fetch the first 5 users and their email addresses.
```

**Response:** 
```
I've executed the `execute_graphql` tool. Here are the results: User 1 (admin@example.com), User 2 (dev@example.com)...
```

**Prompt:** 
```
Explain the performance of this GraphQL query: { users { id name } }
```

**Response:** 
```
Using `explain_graphql`, I've analyzed the query. The generated SQL is 'SELECT id, name FROM users'. The execution plan shows an Index Scan with a cost of 0.00..12.40.
```

**Prompt:** 
```
Check the health of my Hasura server and verify metadata consistency.
```

**Response:** 
```
I've called `check_health` with strict mode. The server is healthy and all metadata is currently consistent.
```

## Capabilities

### Run GraphQL Queries
Execute complex data requests and writes against your database's primary endpoint.

### Inspect Schema Metadata
Manage table definitions, relationships, and permissions programmatically using the dedicated API.

### Analyze Query Performance
Generate SQL execution plans for any GraphQL query so you can pinpoint bottlenecks in your database code.

### Check System Health
Verify the overall status of the Hasura instance, including checking if metadata is consistent.

### Export Database Backups
Initiate a full schema dump for connected Postgres sources when you need to move or archive data.

## Use Cases

### A new feature breaks in production
The Ops Engineer notices a query is timing out. Instead of logging into the database UI, they ask their agent to run `explain_graphql` on the problematic query. The results immediately show that an index scan is failing, allowing them to pinpoint the exact missing index and fix it.

### Migrating data between environments
The Data Engineer needs a fresh copy of the current user table schema for staging. They prompt their agent to use `pg_dump`. The tool runs the export, providing a clean SQL dump file ready for import into the testing environment.

### Validating new API endpoints
The Backend Developer builds a mutation and wants to test it against live data. They use `execute_graphql` with their agent client, running the full query in natural language. The response confirms successful execution, validating the endpoint before code review.

### Troubleshooting inconsistent permissions
The DevOps team suspects a configuration drift between staging and production. They ask the agent to run `get_config` and compare the output against expected values, quickly identifying which specific setting is different.

## Benefits

- Stop guessing if your query will run. `explain_graphql` gives you the actual SQL execution plan so you can optimize performance before deployment.
- Avoid manual schema checks. Run `check_health` to instantly verify metadata consistency across all connected services, preventing runtime errors.
- Handle everything from data reads to writes in one place. Use `execute_graphql` for complex mutations or simple queries without leaving your agent chat.
- When you need a copy of the schema, don't write a script. Simply call `pg_dump` to export full database backups instantly.
- Manage system details cleanly. Get runtime info using `get_config` and verify the exact version with `get_version`, making environment parity easy.

## How It Works

The bottom line is, you tell your AI client what data you need, and it sends the structured request to Hasura, which runs the query against your Postgres database.

1. Subscribe to this MCP and provide your Hasura GraphQL Endpoint URL.
2. Supply the required Admin Secret key for secure connection authorization.
3. Your agent can then call tools like `execute_graphql` or `explain_graphql` using natural language prompts.

## Frequently Asked Questions

**Can I see the actual SQL query that Hasura generates for my GraphQL request?**
Yes! Use the `explain_graphql` tool. It will return the generated SQL and the execution plan from the database, helping you debug performance issues.

**How do I check if my metadata is inconsistent or if the server is down?**
You can use the `check_health` tool. If you set the `strict` parameter to true, it will specifically check for metadata consistency in addition to basic connectivity.

**Is it possible to export my database schema through this server?**
Yes, the `pg_dump` tool allows you to execute a schema dump on your connected Postgres source, which is useful for migrations or backups.

**How do I use `get_config` to see my Hasura server settings?**
It retrieves the current operational configuration of your Hasura instance. This allows you or your agent to confirm global settings, like API key requirements or default connection parameters.

**What kind of operations can I run using `execute_metadata`?**
You can perform programmatic actions on the schema itself. This includes tracking tables, defining new relationships between models, and managing user permissions via the Metadata API.

**Can I use `execute_graphql` to make changes or mutations to my data?**
Yes, `execute_graphql` supports not only queries but also write operations (mutations) and batched requests. You can pass variables directly to perform complex updates on your database.

**How do I check the specific version details of my Hasura engine using `get_version`?**
Calling `get_version` returns the exact software type and running version number. This is useful for auditing or ensuring compatibility when deploying new services.

**Does this MCP handle advanced data manipulation beyond simple reading, like batching requests via `execute_graphql`?**
Yes, it handles batched requests and supports full variable support within GraphQL operations. You can pass multiple related queries or mutations in a single call.