#MCP server

The Hygraph MCP server connects Hygraph directly to AI assistants through the Model Context Protocol (MCP). It allows MCP-compatible tools, such as Claude, Cursor, Windsurf, or VS Code, to securely interact with your Hygraph project using natural language commands.

The Hygraph MCP server acts as a bridge between AI assistants and Hygraph’s Content API, allowing large language models (LLMs) to interact with your Hygraph project in a structured, secure, and standardized way.

#What you can do

The MCP server enables developers and platform teams to build intelligent, compliant AI integrations that feel native to Hygraph, without reinventing API logic for every project. The MCP server reuses the same model and permissions as your PAT. You can configure which models you want to be editable.

It exposes tools that handle discovery, querying, CRUD operations, and publishing. Once connected, AI assistants can read, create, update, and publish content through your existing Hygraph APIs, turning your CMS into an AI-native content platform. Currently, we do not allow delete or unpublish operations via MCP.

Once you have the MCP server up and running, you could perform the following tasks:

• Fetch all blog posts published this week and generate a social media summary.
• Create a new product entry with the specified details and publish it.
• Update all draft posts tagged ‘urgent’ and change their status.
• Check which content models exist in this project.
• Show me the structure of the Product model.
• List all posts with their authors.
• Move content between environments.
• Perform bulk updates or cleanups.
• Generate and publish content automatically based on prompts or structured data.

#Get started

#Availability

• The Hygraph MCP server is available for all projects and is currently in Early Access.

#Steps

To set up the MCP server, perform the following steps:

1. Retrieve the Permanent Auth Token (PAT) from Hygraph Studio.
   • Currently, we do not support OAuth for authentication.
2. Retrieve the MCP Server API endpoint.
3. Configure your MCP client.
   • Claude Code
   • Cursor IDE
   • VS Code
   • Windsurf IDE
   • Claude Desktop

#Retrieve the Permanent Auth Token (PAT)

Hygraph MCP authenticates using a bearer token. You need to supply the Permanent Auth Token (PAT) as the bearer token. If you have not created a PAT, follow the steps here.

To retrieve the PAT, 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.

Important

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.

#Retrieve the MCP Server API 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-YOUR_PROJECT_HOSTED_REGION.hygraph.com/YOUR_PROJECT_IDENTIFIER/YOUR_ENVIRONMENT_NAME/mcp

#Set up the MCP client

Each MCP client handles HTTP servers and authentication differently.

#Claude Code

Claude Code has native support for HTTP MCP servers with auth headers.

Method 1 (Recommended) - Use environment variables

set your token as an env var

export HYGRAPH_TOKEN="your_token_here"

reference it in the command

claude mcp add --transport http \

--header "Authorization: Bearer ${HYGRAPH_TOKEN}" \

hygraph https://mcp-YOUR_PROJECT_HOSTED_REGION.hygraph.com/YOUR_PROJECT_IDENTIFIER/YOUR_ENVIRONMENT_NAME/mcp

Copy

Method 2 - Add the server with your bearer token

--header "Authorization: Bearer YOUR_HYGRAPH_TOKEN" \

Copy

Verification

list configured servers

claude mcp list

start claude and test

claude

/mcp

you should see hygraph listed

Copy

To define the project scope, use these arguments:

• --scope local - only this project (default)
• --scope user - all your projects
• --scope global - system-wide

#Cursor IDE

Warning

Models selected through the Auto mode in Cursor cannot handle our MCP server. We recommend that you select a model manually.

1. In Cursor, navigate to Settings.
2. In the MCP Servers section, click Add Server or Add Custom MCP.
3. As per your requirement, paste one of the following configuration:
   • Project-specific configuration - In .cursor/mcp.json file in your repository
     {
     "mcpServers": {
     "hygraph": {
     "command": "npx",
     "args": [
     "-y",
     "mcp-remote@latest",
     "https://mcp-YOUR_PROJECT_HOSTED_REGION.hygraph.com/YOUR_PROJECT_IDENTIFIER/YOUR_ENVIRONMENT_NAME/mcp",
     "--header",
     "Authorization: Bearer YOUR_TOKEN_HERE"
     ]
     }
     }
     }
     Copy
   • Global configuration - In .cursor/mcp.json file in your repository
     {
     "mcpServers": {
     "hygraph": {
     "command": "npx",
     "args": [
     "-y",
     "mcp-remote@latest",
     "https://mcp-YOUR_PROJECT_HOSTED_REGION.hygraph.com/YOUR_PROJECT_IDENTIFIER/YOUR_ENVIRONMENT_NAME/mcp",
     "--header",
     "Authorization: Bearer ${HYGRAPH_TOKEN}"
     ],
     "env": {
     "HYGRAPH_TOKEN": "your_token_here"
     }
     }
     }
     }
     Copy

#VS Code

VS Code has built-in MCP support. For more information on adding an MCP server, read the VS Code docs.

In the .vscode/mcp.json file, add the following configuration:

{

"servers": {

"hygraph": {

  "url": "https://mcp-YOUR_PROJECT_HOSTED_REGION.hygraph.com/YOUR_PROJECT_IDENTIFIER/YOUR_ENVIRONMENT_NAME/mcp",

  "type": "http",

  "headers": {

    "Authorization": "Bearer ${HYGRAPH_TOKEN}"

  }

}

},

"inputs": [

{

  "type": "promptString",

  "id": "HYGRAPH_TOKEN",

  "description": "Hygraph API Token",

  "password": true

}

]

}

Copy

Alternatively, you can use mcp-remote:

{

"servers": {

"hygraph": {

  "command": "npx",

  "args": [

    "-y",

    "mcp-remote@latest",

    "https://mcp-YOUR_PROJECT_HOSTED_REGION.hygraph.com/YOUR_PROJECT_IDENTIFIER/YOUR_ENVIRONMENT_NAME/mcp",

    "--header",

    "Authorization: Bearer ${HYGRAPH_TOKEN}"

  ],

  "env": {

    "HYGRAPH_TOKEN": "your_token_here"

  }

}

}

}

Copy

#Windsurf IDE

1. Navigate to Windsurf Settings.
2. Scroll to Cascade → MCP Servers.
3. Click Add Server.
4. In the ~/.codeium/windsurf/mcp_config.json file, paste the following configuration:
   {
   "mcpServers": {
   "hygraph": {
   "command": "npx",
   "args": [
   "-y",
   "mcp-remote@latest",
   "https://mcp-YOUR_PROJECT_HOSTED_REGION.hygraph.com/YOUR_PROJECT_IDENTIFIER/YOUR_ENVIRONMENT_NAME/mcp",
   "--header",
   "Authorization: Bearer ${HYGRAPH_TOKEN}"
   ],
   "env": {
   "HYGRAPH_TOKEN": "your_token_here"
   }
   }
   }
   }
   Copy
5. Click Refresh Servers.

#Claude Desktop

1. Edit your config file at:
   • 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, and click Edit Config. This takes you directly to the file. Open it and follow the steps below.
2. Add the following to your config file:
   "mcpServers": {
   "hygraph": {
   "command": "npx",
   "args": [
   "mcp-remote@latest",
   "https://mcp-YOUR_PROJECT_HOSTED_REGION.hygraph.com/YOUR_PROJECT_IDENTIFIER/YOUR_ENVIRONMENT_NAME/mcp",
   "--header", "Authorization: Bearer YOUR_HYGRAPH_TOKEN"
   ]
   }
   }
   Copy
3. Quit and reopen Claude Desktop.

For more information on setting up an MCP server, see Claude documentation.

#Use MCP server tools

Once your MCP server is running, you can start interacting with models and entries in your Hygraph project.

For example, you can write the following prompts:

• List all blog posts from Hygraph, and then create individual Markdown files for each post with front matter including slug, title, and publish date.
• Find all posts with status DRAFT that have 'urgent' in the title, update their priority field to 'high', then publish them.
• Generate TypeScript types for all content models in Hygraph.

#Troubleshooting

#Authorization failed / 401 error

Check if:

• You can test the token in the Hygraph API playground.
• The token has the required permissions for the operation.
• The header format is correct — Authorization: Bearer YOUR_TOKEN.
• There are no extra quotes around the token.

#Server not found in client error

For stdio clients (Cursor/Windsurf):

• Verify npx is installed (which npx).
• Test mcp-remote manually.
  npx -y mcp-remote@latest YOUR_ENDPOINT --header "Authorization: Bearer TOKEN"
  Copy

For Claude Code:

• Run claude mcp get hygraph to check the config.
• Run claude mcp logs hygraph to 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 client.
2. Check the MCP server list/status.
3. Check server logs.
4. Verify network access to Hygraph endpoint, and permissions associated with the Hygraph token.

#mcp-remote connection issues

The mcp-remote package is used to connect stdio-based MCP clients, such as Cursor or Windsurf to HTTP endpoints. For more information, see the official docs. If you face mcp-remote connection issues, you can:

• Update to the latest version - npm install -g mcp-remote@latest.
• Use the absolute path of npx in the config file. Run which npx to find the absolute path.
• Check if node version is >=20.18.1.

#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.
• Use separate tokens per environment. An example config for multi-environment configuration:
  {
  "mcpServers": {
  "hygraph-prod": {
  "command": "npx",
  "args": [
  "mcp-remote",
  "https://mcp-YOUR_PROJECT_HOSTED_REGION.hygraph.com/YOUR_PROJECT_IDENTIFIER/YOUR_ENVIRONMENT_NAME/mcp",
  "--header",
  "Authorization: Bearer ${HYGRAPH_PROD_TOKEN}"
  ],
  "env": {
  "HYGRAPH_PROD_TOKEN": "token_here"
  }
  },
  "hygraph-staging": {
  "command": "npx",
  "args": [
  "mcp-remote",
  "https://mcp-YOUR_PROJECT_HOSTED_REGION.hygraph.com/YOUR_PROJECT_IDENTIFIER/YOUR_ENVIRONMENT_NAME/mcp",
  "--header",
  "Authorization: Bearer ${HYGRAPH_STAGING_TOKEN}"
  ],
  "env": {
  "HYGRAPH_STAGING_TOKEN": "token_here"
  }
  }
  }
  }
  Copy

Access control:

• Configure Content API permissions in Hygraph.
• Audit token usage regularly.