Configuration

Configuration options for the Nhost MCP tool

This document describes all available configuration options for the Nhost MCP tool. The configuration file uses TOML format and supports environment variable interpolation.

Configuration File Location

The configuration file is located at .nhost/mcp-nhost.toml in your project directory. You can specify a custom location using the --config-file flag.

TOML

# Cloud configuration for managing Nhost Cloud projects and organizations
# Remove this section to disable Nhost Cloud access
[cloud]
# Enable mutations on Nhost Cloud (project configuration, organization management, etc.)
# When false, only queries are allowed
# Requires your personal access token from CLI credentials
enable_mutations = true

# Project-specific configurations
# You can configure multiple projects (local or cloud)
[[projects]]
# Project subdomain (required)
# For local projects, use "local"
subdomain = "your-project-subdomain"

# Project region (required)
# For local projects, use "local"
region = "your-project-region"

# Optional: Project description for better identification
description = "Production project for my app"

# Authentication: Use either admin_secret or pat
# Admin secret for project access
admin_secret = "your-project-admin-secret"
# OR
# Project-specific PAT (Personal Access Token)
pat = "your-project-pat"

# Enable metadata management (migrations, permissions, etc.)
# Requires admin_secret to be set
# When enabled, the manage-graphql tool can create migrations and manage Hasura metadata
manage_metadata = false

# List of allowed GraphQL queries
# Use ["*"] to allow all queries
# Use [] to disable all queries
# Use specific query names to allow only those queries
allow_queries = ["*"]

# List of allowed GraphQL mutations
# Use ["*"] to allow all mutations
# Use [] to disable all mutations
# Use specific mutation names to allow only those mutations
allow_mutations = ["*"]

# Optional: Custom GraphQL URL
# Default: https://{subdomain}.graphql.{region}.nhost.run/v1
# For local: https://local.graphql.local.nhost.run/v1
graphql_url = "your-custom-url"

# Optional: Custom Auth URL
# Default: https://{subdomain}.auth.{region}.nhost.run/v1
# For local: https://local.auth.local.nhost.run/v1
auth_url = "your-custom-url"

# Optional: Custom Hasura URL (for metadata management)
# Default: https://{subdomain}.hasura.{region}.nhost.run
# For local: https://local.hasura.local.nhost.run
hasura_url = "your-custom-url"

Example Configurations

Basic Configuration with Cloud Access

# Enable Nhost Cloud management with mutations
[cloud]
enable_mutations = true

# Configure a production project
[[projects]]
subdomain = "my-app"
region = "eu-central-1"
description = "Production project"
pat = "nhp_production_pat"
allow_queries = ["*"]
allow_mutations = ["insertPost", "updatePost", "deletePost"]

Local Development Configuration

# Configure local development environment
[[projects]]
subdomain = "local"
region = "local"
description = "Local development project running via the Nhost CLI"
admin_secret = "nhost-admin-secret"
manage_metadata = true
allow_queries = ["*"]
allow_mutations = ["*"]

Multiple Projects with Different Access Levels

# Enable cloud management
[cloud]
enable_mutations = true

# Local development with full access
[[projects]]
subdomain = "local"
region = "local"
description = "Local development project running via the Nhost CLI"
admin_secret = "nhost-admin-secret"
manage_metadata = true
allow_queries = ["*"]
allow_mutations = ["*"]

# Production project with restricted access
[[projects]]
subdomain = "my-app-prod"
region = "eu-central-1"
description = "Production project"
pat = "nhp_prod_pat"
allow_queries = ["*"]
allow_mutations = ["insertPost", "updatePost"]

# Staging project with read-only access
[[projects]]
subdomain = "my-app-staging"
region = "eu-central-1"
description = "Staging project"
pat = "nhp_staging_pat"
allow_queries = ["*"]
allow_mutations = []

Environment Variable Interpolation

You can use environment variables in your configuration:

[cloud]
enable_mutations = true

[[projects]]
subdomain = "my-app"
region = "eu-central-1"
description = "Production project"
# Use ${VAR_NAME} syntax to interpolate environment variables
admin_secret = "${NHOST_ADMIN_SECRET}"
allow_queries = ["*"]
allow_mutations = ["*"]

Configuration Options Reference

Cloud Section

Option	Type	Required	Description
enable_mutations	boolean	No	Enable mutations on Nhost Cloud. Defaults to false. Requires CLI credentials with PAT.

Projects Section

Option	Type	Required	Description
subdomain	string	Yes	Project subdomain. Use "local" for local development projects.
region	string	Yes	Project region. Use "local" for local development projects.
description	string	No	Human-readable description of the project.
admin_secret	string	No*	Admin secret for authentication. Either admin_secret or pat is required.
pat	string	No*	Project-specific Personal Access Token. Either admin_secret or pat is required.
manage_metadata	boolean	No	Enable metadata management (migrations, permissions, etc.). Requires admin_secret. Defaults to false.
allow_queries	array	No	List of allowed query names. Use ["*"] for all, [] for none. Defaults to [].
allow_mutations	array	No	List of allowed mutation names. Use ["*"] for all, [] for none. Defaults to [].
graphql_url	string	No	Custom GraphQL endpoint URL. Auto-generated if not provided.
auth_url	string	No	Custom Auth endpoint URL. Auto-generated if not provided.
hasura_url	string	No	Custom Hasura endpoint URL. Auto-generated if not provided. Required for manage_metadata.

* Either admin_secret or pat must be provided for authentication.