Development Setup

This guide sets up the Nhost CLI’s MCP server against your local project so an AI assistant can read your GraphQL schema, run queries and mutations, and manage Hasura metadata and migrations while you develop.

Prerequisites

• The Nhost CLI installed.
• A local project running with nhost up. The local GraphQL endpoint is https://local.graphql.local.nhost.run/v1.
• An MCP-compatible client such as Claude Code or Cursor.

Let an AI assistant set it up

If you already have an AI assistant connected to your editor, it can perform the whole setup for you. Give it the onboarding file and let it run:

Claude Code

curl -fsSL https://docs.nhost.io/install-mcp | claude

Codex CLI

curl -fsSL https://docs.nhost.io/install-mcp | codex exec -

Gemini CLI

curl -fsSL https://docs.nhost.io/install-mcp | gemini

Cursor

Open Cursor’s Agent chat, paste the prompt below, and let it run the setup:

Set up the Nhost MCP server for my local project: https://docs.nhost.io/install-mcp

Other

curl -fsSL https://docs.nhost.io/install-mcp | <your-assistant-cli>

You can also hand any coding assistant the link https://docs.nhost.io/install-mcpCopy linkCopied! to run the setup autonomously. Prefer the manual steps below? Continue reading.

1. Create the configuration file

The MCP server reads .nhost/mcp-nhost.toml from your project directory. Generate it with the interactive wizard:

nhost mcp config

Or create .nhost/mcp-nhost.toml yourself with a single local project. This grants the assistant full read/write access to your local project and enables metadata management:

[[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 = ["*"]

Caution

These settings are meant for local development only. admin_secret bypasses permissions, and allow_mutations = ["*"] lets the assistant modify data. Never point this configuration at a production project. See the configuration reference for how to scope access with allow_queries, allow_mutations, and per-project PATs.

2. Register the server with your client

Point your client at nhost mcp start. The server picks up .nhost/mcp-nhost.toml automatically.

Claude Code

claude mcp add nhost nhost mcp start

Codex CLI

codex mcp add nhost -- nhost mcp start

Gemini CLI

gemini mcp add nhost nhost mcp start

Cursor

Add the following to your mcpServers configuration:

{
  "mcpServers": {
    "nhost": {
      "command": "nhost",
      "args": ["mcp", "start"]
    }
  }
}

For per-client configuration details, see MCP Clients.

3. Verify

Your client should now list the nhost server and its tools: graphql-query, get-schema, manage-graphql, and search. Ask the assistant to fetch your schema, or confirm the server responds directly:

echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get-schema","arguments":{"subdomain":"local","role":"admin","summary":true}},"id":1}' | nhost mcp start

If something is not working, see Troubleshooting.

Next steps

• Configuration — scope which queries and mutations the assistant can run.
• MCP Clients — per-client configuration details.
• Overview — the full list of tools and resources the server exposes.