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.

#Prerequisites

Before you begin, ensure you have:

#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

#Step 3 - Configure your MCP client

Each MCP client handles HTTP servers and authentication differently. Choose your client:

• Claude Code
• Cursor IDE
• VS Code
• Windsurf IDE
• Claude Desktop

#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.

#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

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. 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.

#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.

#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:

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) 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.