This guide walks you through connecting an AI assistant to your Hygraph project. For an overview of what the MCP server can do, see MCP server overview.

#Connection modes

Hygraph exposes two MCP endpoints.

#Project endpoint (Permanent Auth Token)

Use the project endpoint when you want a fixed project and environment, and you want the assistant limited to that token's permissions.

https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp

#Global endpoint (Hygraph login)

Use the global endpoint when the assistant should see every project you can access, then pick a project and environment in conversation. The Claude connector uses the global endpoint.

https://mcp.hygraph.com/mcp

#Prerequisites

• Node.js >= 20.18.1 (required for mcp-remote)
• npx included with Node.js. Verify with which npx
• Permanent Auth Token (PAT)

#Permissions reference

All MCP operations are governed by the permissions on your Permanent Auth Token (PAT).

To fully leverage the MCP server's functionality, you need the Read, Create, Update, and Publish permissions. If you only intend to retrieve content, the Read permission is sufficient. For more information on setting up these permissions, see our docs on Configuring permissions for Permanent Auth Tokens.

Delete operations are never supported via MCP, for both content and schema. Destructive actions must be performed manually in Hygraph Studio. For more information, see Safety guardrails.

#Step 1 - Create a PAT

Hygraph MCP authenticates using a bearer token. You need to supply the Permanent Auth Token (PAT) as the bearer token.

If you haven't created a PAT yet, follow these steps:

1. In your Hygraph project, go to Project Settings.
2. Under Access, select Permanent Auth Tokens.
3. Click Generate MCP PAT.
4. Choose the appropriate permission set (see Permissions reference), then click Generate MCP PAT.
5. Copy the generated token.

If you've previously created a PAT and want to use it for the MCP server, follow these steps:

1. In your Hygraph project, go to Project Settings.
2. Under Access, click Permanent Auth Tokens.
3. Copy the PAT that you want to use to configure the MCP server.

#Step 2 - Get your MCP endpoint

To find the MCP Server API endpoint, follow these steps:

1. In your Hygraph project, go to Project Settings.
2. Under Access, select Endpoints.
3. Under MCP Server API, copy the endpoint.

   https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp

   Copy

This is the project endpoint. It's locked to one project and one environment. If you want a single connection that spans every project you can access instead, use the global endpoint below.

#Step 3 - Configure your MCP client

Each MCP client handles HTTP servers and authentication differently.

Choose your client:

#Claude Code

Claude Code has native HTTP MCP support with auth headers and does not require mcp-remote.

Recommended: Use an environment variable.

export HYGRAPH_TOKEN="your_token_here"

claude mcp add hygraph https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp \
  --transport http \
  --header "Authorization: Bearer ${HYGRAPH_TOKEN}"

Alternative: Use an inline token.

claude mcp add hygraph https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_HYGRAPH_TOKEN"

Scope options:

Verify the setup:

# list configured servers
claude mcp list
claude
> /mcp
# Hygraph should appear in the list

If you see errors, run claude mcp logs hygraph or see Troubleshooting.

#Claude connector

The Claude connector uses the global endpoint, authenticated with your Hygraph login instead of a PAT.

1. In Claude, go to Settings > Connectors, find Hygraph MCP, and select Connect. Otherwise, you can also find the Hygraph MCP connector directly in the Claude directory.
2. Sign in to Hygraph when prompted, and click Accept.
   • You might see a message that you Allow offline access. This enables Claude to keep working on Hygraph tasks in the background or on a schedule, without the app open.

After connecting, ask Claude to list your Hygraph projects, pick an environment, then run content or schema tasks.

Claude asks for permission before it uses certain tools. Choose Allow once to approve a single call, or Always allow to skip that prompt for the rest of the conversation. See the tools reference for the full list.

Enable the Hygraph MCP connector for your Claude Chat. Click + > Connectors, and turn on the toggle for Hygraph MCP.

• What Hygraph projects can I access?
• List the environments for project, then show the content models in the master environment.

If any of your editors want to connect Claude themselves, without this level of technical detail, point them to Connect an AI assistant to Hygraph. It walks through the same connector from a non-technical angle.

#Cursor IDE

Cursor uses mcp-remote to connect to HTTP MCP endpoints.

Recommended method: Use the one-click install from Hygraph Studio to install the MCP server in Cursor.

1. In your Hygraph project, go to Project Settings.
2. Under Access, select Endpoints.
3. Under MCP Server API, click Add to Cursor.
4. Select the Permanent Auth Token you want to use for the MCP server.
5. Click Add to Cursor. When prompted, open Cursor. You are redirected to the MCP server setup page in Cursor.
6. Review the settings and click Install. You should see the MCP server listed in the MCP Servers section in Cursor.

Alternate method: Install the MCP server manually.

1. In Cursor, navigate to Settings.

2. In the MCP Servers section, click Add Server or Add Custom MCP.

3. Paste one of the following configurations:

   • Project-specific configuration: In the .cursor/mcp.json file in your repository

   {
     "mcpServers": {
       "hygraph": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote@latest",
           "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp",
           "--header",
           "Authorization: Bearer YOUR_TOKEN_HERE"
         ]
       }
     }
   }

   Copy
   • Global: Add to your user-level ~/.cursor/mcp.json file.

   {
     "mcpServers": {
       "hygraph": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote@latest",
           "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp",
           "--header",
           "Authorization: Bearer ${HYGRAPH_TOKEN}"
         ],
         "env": {
           "HYGRAPH_TOKEN": "your_token_here"
         }
       }
     }
   }

   Copy

#VS Code

VS Code has built-in MCP support. Add the following to .vscode/mcp.json:

{
  "servers": {
    "hygraph": {
      "url": "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${HYGRAPH_TOKEN}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "HYGRAPH_TOKEN",
      "description": "Hygraph API Token",
      "password": true
    }
  ]
}

Alternatively, use mcp-remote:

{
  "servers": {
    "hygraph": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp",
        "--header",
        "Authorization: Bearer ${HYGRAPH_TOKEN}"
      ],
      "env": {
        "HYGRAPH_TOKEN": "your_token_here"
      }
    }
  }
}

For more information, see the VS Code MCP docs.

#Windsurf IDE

1. Go to Windsurf Settings → Cascade → MCP Servers → Add Server.

2. In ~/.codeium/windsurf/mcp_config.json, add:

   {
     "mcpServers": {
       "hygraph": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote@latest",
           "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp",
           "--header",
           "Authorization: Bearer ${HYGRAPH_TOKEN}"
         ],
         "env": {
           "HYGRAPH_TOKEN": "your_token_here"
         }
       }
     }
   }

   Copy

3. Click Refresh Servers.

#Claude Desktop

This is the project endpoint, configured manually with a PAT and mcp-remote. For a no-code, login-based setup instead, use the Claude connector.

1. Open the config file:

   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/config.json

   If you can't find the config file, in Claude Desktop, go to Settings → Developer → Edit Config.

2. Add the following:

   {
     "mcpServers": {
       "hygraph": {
         "command": "npx",
         "args": [
           "mcp-remote@latest",
           "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp",
           "--header",
           "Authorization: Bearer YOUR_HYGRAPH_TOKEN"
         ]
       }
     }
   }

   Copy

3. Quit and reopen Claude Desktop.

#Multi-environment configuration

For production use, we recommend using separate tokens per environment. The example below uses mcp-remote, which is compatible with Cursor, Windsurf, and Claude Desktop (PAT). For Claude Code, replace the command/args block with the --transport http syntax shown in the Claude Code section above.

{
  "mcpServers": {
    "hygraph-prod": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/master/mcp",
        "--header",
        "Authorization: Bearer ${HYGRAPH_PROD_TOKEN}"
      ],
      "env": {
        "HYGRAPH_PROD_TOKEN": "token_here"
      }
    },
    "hygraph-staging": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/staging/mcp",
        "--header",
        "Authorization: Bearer ${HYGRAPH_STAGING_TOKEN}"
      ],
      "env": {
        "HYGRAPH_STAGING_TOKEN": "token_here"
      }
    }
  }
}

#Start using the MCP server

Once your MCP server is running, verify the connection is working by asking your AI assistant a simple question about your project:

• What content models exist in my Hygraph project?
• List the fields on my content models.

If the assistant returns accurate results, your connection is set up correctly. If not, see Troubleshooting.

First tasks to try:

• List all entries with status DRAFT. This confirms read access is working.
• Create a test entry and publish it. This confirms write and publish permissions are working.
• Show me the structure of my Product model, and add a field to it. This confirms schema access is working.

Verify in Hygraph Studio:

After trying the tasks above, go to Hygraph Studio and check the results directly:

• Open the Content section to confirm new or updated entries appear as expected.
• Check the Schema section to verify any models or fields that were created.
• Review entry status to confirm published entries are live.

This is a good way to confirm that the AI assistant's actions have taken effect.

Tips for better results:

• Be specific about model names and field names. Your AI assistant will use them exactly as given.
• For bulk operations, describe the filter criteria clearly before stating the action. For example: Find all entries tagged urgent and update their priority to High.
• If a result is unexpected, ask the assistant to explain what query it ran. This helps catch permission or field name issues quickly.

Watch the following video for a practical demonstration of the Hygraph MCP server in action. This video walks through setting up and interacting with the MCP server from Cursor, showing how AI assistants can query content, inspect schema, and perform workflows using natural language.

Watch

#Security best practices

Token storage:

• Use environment variables to store tokens. Do not commit tokens to a remote repository.
• Set up secret management in CI/CD.

Token permissions:

• Create role-specific tokens in Hygraph.
• Use read-only tokens for read-only workflows.

Access control:

• Configure Content API permissions and Management API permissions in Hygraph.
• Audit token usage regularly.
• If you use the global endpoint, review user's permissions across every project they belong to.

#Troubleshooting

#401 Authorization failed

• Verify the token works in the Hygraph API playground.
• Check the token has the correct permissions for the operation (see Permissions reference).
• Confirm the header format is correct with no extra quotes or spaces: Authorization: Bearer YOUR_TOKEN.

#Claude asks for a project or environment on every call

That's expected on https://mcp.hygraph.com/mcp. Ask it to call list_projects and list_environments first, then keep using those values. It's not expected on a project-scoped URL.

#Hygraph login succeeds but tools fail

Confirm the Hygraph user can access the project in Studio. The global endpoint uses that user's permissions, not a PAT. Agent tools still require a project and environment, and they only appear when that environment has an agent.

#MCP tools not showing or queries failing

If the MCP server connects but you cannot run queries or create entries, required tools might be disabled:

1. In your AI assistant settings, go to Connectors.
2. Find the Hygraph MCP connector and click Configure.
3. Review tool permissions, and ensure the required tools are enabled. You can set Allow all tools for simplicity, or use Custom to enable specific tools.

#Server not found

For Cursor / Windsurf (stdio clients):

Verify npx is available:

which npx

Test mcp-remote directly:

npx -y mcp-remote@latest YOUR_ENDPOINT --header "Authorization: Bearer TOKEN"

For Claude Code:

claude mcp get hygraph   # check config
claude mcp logs hygraph  # check logs

For Claude Desktop (PAT):

If you're using NPM to manage Node versions, make sure you uninstall any NPM versions earlier than 22.

#MCP server tools not displayed

1. Restart your IDE or MCP client.
2. Check the MCP server status in your client's settings.
3. Review server logs.
4. Verify network access to Hygraph endpoint, and permissions associated with the Hygraph token.

#mcp-remote connection issues

mcp-remote is required for stdio-based clients (Cursor, Windsurf, Claude Desktop with a PAT) to connect to HTTP endpoints. If you face mcp-remote connection issues, you can:

• Update to the latest version: npm install -g mcp-remote@latest
• Use the absolute npx path in your config (which npx to find it).
• Ensure Node.js version is >= 20.18.1.

For more, see the mcp-remote npm page.

#What's next

• MCP server: What the MCP server does, its key benefits, and its safety guardrails.
• MCP tools reference: Look up every MCP tool, what it does, and which endpoint it's available on.
• AI Agents: How manual and workflow-bound agents differ, and how to configure one for MCP triggering.
• AI Guidelines: Create and assign guidelines that AI tools can read.