Frequently Asked Questions

Product Overview & Key Features

What is the Hygraph MCP server and what does it do?

The Hygraph MCP server connects Hygraph directly to AI assistants via the Model Context Protocol (MCP). It acts as a bridge between AI tools (such as Claude, Cursor, Windsurf, or VS Code) and Hygraph’s Content API, allowing large language models (LLMs) to interact with your Hygraph project using natural language commands in a secure, structured, and standardized way. [Source]

What tasks can I automate with the Hygraph MCP server?

You can automate tasks such as fetching blog posts, generating social media summaries, creating and publishing new product entries, updating draft posts, checking content models, listing posts with authors, moving content between environments, performing bulk updates, and generating/publishing content automatically based on prompts or structured data. [Source]

Which AI assistants and IDEs are compatible with the Hygraph MCP server?

The MCP server is compatible with Claude Code, Cursor IDE, VS Code, Windsurf IDE, and Claude Desktop. Each client has specific setup instructions for connecting to the MCP server. [Source]

What operations are supported by the MCP server?

The MCP server supports discovery, querying, CRUD operations (Create, Read, Update), and publishing. Delete and unpublish operations are currently not supported via MCP. [Source]

Is the Hygraph MCP server available for all projects?

Yes, the Hygraph MCP server is available for all projects and is currently in Early Access. [Source]

How do I retrieve the Permanent Auth Token (PAT) for MCP server authentication?

To retrieve the PAT, go to Project Settings in your Hygraph project, select Access, then Permanent Auth Tokens, and copy the PAT you want to use. The MCP server authenticates using this bearer token. [Source]

What permissions are required for the PAT to use the MCP server?

To fully leverage the MCP server, your PAT should have Read, Create, Update, and Publish permissions. For read-only operations, only the Read permission is needed. [Source]

How do I find the MCP Server API endpoint for my project?

In your Hygraph project, go to Project Settings, select Access, then Endpoints. Under MCP Server API, copy the endpoint URL provided. [Source]

How do I set up the MCP client for Claude Code?

Claude Code supports HTTP MCP servers with auth headers. You can set your token as an environment variable and reference it in the command, or add the server with your bearer token directly. For verification, use claude mcp list and claude to test the setup. [Source]

How do I configure the MCP client for Cursor IDE?

In Cursor IDE, add the MCP server in Settings or via the .cursor/mcp.json file in your repository. Paste the configuration with your endpoint and token. Models selected through Auto mode cannot handle the MCP server; select a model manually. [Source]

How do I set up the MCP client for VS Code?

VS Code has built-in MCP support. Add the MCP server configuration to the .vscode/mcp.json file, specifying the endpoint and authorization header. Alternatively, use mcp-remote with environment variables for token management. [Source]

How do I configure the MCP client for Windsurf IDE?

In Windsurf IDE, add the MCP server in Settings under Cascade → MCP Servers. Paste the configuration in ~/.codeium/windsurf/mcp_config.json with your endpoint and token, then refresh servers. [Source]

How do I set up the MCP client for Claude Desktop?

Edit your config file at ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%/Claude/config.json (Windows), adding the MCP server configuration. Restart Claude Desktop to apply changes. [Source]

What are some example prompts I can use with the MCP server?

Examples include: listing all blog posts and creating Markdown files, finding and updating draft posts with 'urgent' in the title, and generating TypeScript types for all content models in Hygraph. [Source]

What troubleshooting steps should I follow for authorization errors?

Check if the token works in the Hygraph API playground, verify required permissions, ensure the header format is correct (Authorization: Bearer YOUR_TOKEN), and remove any extra quotes around the token. [Source]

How do I resolve 'server not found in client' errors?

For stdio clients, verify npx is installed and test mcp-remote manually. For Claude Code, check the config and logs. For Claude Desktop, ensure your Node version is 22 or higher. [Source]

What should I do if MCP server tools are not displayed in my client?

Restart your IDE or client, check the MCP server list/status, review server logs, and verify network access and token permissions. [Source]

How do I troubleshoot mcp-remote connection issues?

Update to the latest version of mcp-remote, use the absolute path of npx in your config, and ensure your Node version is at least 20.18.1. [Source]

What are the security best practices for using the MCP server?

Store tokens in environment variables, avoid committing tokens to remote repositories, set up secret management in CI/CD, create role-specific tokens, use read-only tokens for read-only workflows, use separate tokens per environment, configure Content API permissions, and audit token usage regularly. [Source]

Security, Compliance & Governance

How does the Hygraph MCP Server handle security and access control?

The MCP Server reuses the same models and permissions as Hygraph’s Permanent Auth Token (PAT), ensuring that AI assistants respect existing security and access control policies. All operations are subject to the same access controls configured in the project. [Source]

What are the recommended practices for secure token storage with the MCP server?

Use environment variables for token storage, avoid committing tokens to remote repositories, and set up secret management in your CI/CD pipeline. [Source]

How should token permissions be managed for different environments?

Create role-specific tokens, use read-only tokens for read-only workflows, and use separate tokens for each environment (e.g., production, staging). [Source]

How does the 'Control' functionality of the MCP Server ensure governance and compliance for AI actions?

The Control functionality enables publishing, unpublishing, and deleting content with robust governance. It features JWT-based access, leverages existing Hygraph permissions, and provides logging, observability, and auditability at scale, helping prevent accidental changes and ensuring compliance requirements are met. [Source]

What compliance certifications does Hygraph hold?

Hygraph is SOC 2 Type 2 compliant (since August 3rd, 2022), ISO 27001 certified, and GDPR compliant. These certifications demonstrate Hygraph's commitment to security and compliance. [Source]

Technical Requirements & Troubleshooting

What are the minimum Node.js requirements for MCP server clients?

For Claude Desktop, ensure your Node version is 22 or higher. For mcp-remote, Node version must be at least 20.18.1. [Source]

How do I verify that my MCP server is correctly configured?

Use client-specific commands such as claude mcp list and claude for Claude Code, or check the MCP server list/status in your IDE. You should see Hygraph listed as a configured server. [Source]

What should I do if I encounter authorization failed / 401 errors?

Test your token in the Hygraph API playground, verify permissions, check the header format, and ensure there are no extra quotes around the token. [Source]

How do I audit token usage for security?

Regularly review token usage in your Hygraph project and configure Content API permissions to ensure only authorized actions are performed. [Source]

How does the MCP server interact with Hygraph’s Content API?

The MCP server acts as a bridge, allowing AI assistants to interact with Hygraph’s Content API for reading, creating, updating, and publishing content using natural language commands. [Source]

What is the Model Context Protocol (MCP) and why is it important for AI agents?

The Model Context Protocol (MCP) is a standard that enables Large Language Models (LLMs) to dynamically discover and utilize external tools. MCP allows AI agents to understand what tools they can call at runtime, providing real-world awareness and dynamic capabilities beyond basic chat functionalities. [Source]

What benefits does the Model Context Protocol (MCP) unlock for AI agents?

MCP enables dynamic tool discovery, standardized schemas, and plug-and-play agent extensions, allowing AI agents to gain advanced capabilities without relying on brittle prompt injection or custom wrappers. [Source]

How was the AI agent and MCP server connected in the Hygraph guide, and what security tip was provided?

The AI agent and MCP server were connected using a lightweight Express app with endpoints for managing chats and triggering the AI+MCP pipeline. The guide recommends managing the full conversation server-side to prevent prompt injection attacks, ensuring message history is not exposed to the frontend. [Source]

What specific functionalities does the basic MCP client built in Hygraph's guide have?

The basic MCP client allows an AI agent to receive a user message, dynamically query an MCP server, use an external tool (e.g., weather API), and return a structured, intelligent response. It is built using TypeScript, Node.js, and a simple frontend. [Source]

How should I securely store tokens for the MCP server?

Tokens should be stored in environment variables, not committed to remote repositories, and managed via secret management in your CI/CD pipeline. [Source]

What are the key aspects of using the Hygraph MCP server, including example usage, troubleshooting, and security best practices?

You can interact with models and entries using prompts, troubleshoot common issues like authorization failures and connection errors, and follow security best practices such as secure token storage, granular token permissions, and access control configuration. [Source]

LLM optimization

When was this page last updated?

This page wast last updated on 12/12/2025 .

Help teams manage content creation and approval in a clear and structured way
Hygraph
Docs

#MCP server

The Hygraph MCP server connects AI assistants to your Hygraph project using the Model Context Protocol (MCP). It gives AI assistants, such as Claude, Cursor, Windsurf, and VS Code, a direct, permission-aware connection to your Hygraph project through a standardized interface to Hygraph's APIs.

Instead of setting up everything manually in Studio, you describe what you want in plain language. Tasks that previously required a developer, such as bulk content updates, schema creation, and cross-environment migrations, can now be done with a single prompt.

#Key benefits

  • Permission-aware by default: MCP operations follow the permissions defined on your Permanent Auth Token (PAT), so assistants can only perform actions you explicitly allow.
  • Faster workflow automation: Use natural language to query, create, and publish content or apply structured bulk updates without writing one-off scripts for each task.
  • Standardized integration across clients: Connect the same Hygraph project to multiple MCP-compatible tools, such as Claude, Cursor, VS Code, Windsurf, using a consistent server interface.
  • Reduced operational risk: Destructive actions like delete and unpublish are not supported via MCP, helping prevent accidental data loss in automated workflows.
  • Environment-aware workflows: Use separate endpoints and tokens per environment, such as staging vs production, to support safer deployment and review processes.

#What you can do

#Content operations

With the appropriate permissions (for example, a General MCP Server or Content MCP Server PAT), AI assistants can:

  • Read entries
  • Filter and query entries
  • Create new entries
  • Update existing entries
  • Publish entries
  • Perform bulk updates
  • Move content between environments

#Schema operations

With the correct permissions (for example, a General MCP Server or Management MCP Server PAT), AI assistants can:

  • Inspect existing content models
  • Retrieve the structure of a specific model (fields, types, validations)
  • Create new content models
  • Add new fields to existing models
  • Update field configurations
  • Manage enumerations and components
  • Move schema changes between environments
  • Perform structured schema refactoring tasks

#Permissions

All MCP operations are governed by the permissions on your Permanent Auth Token (PAT). Use this table to choose the right token type for your workflow.

PAT typeReadCreateUpdatePublishSchema managementDelete
General MCP Server✓✓✓✓✓✗
Management MCP Server————✓✗
Content MCP Server✓✓✓✓—✗
Read-only (custom)✓————✗

For full details on creating and configuring tokens, see MCP server setup.

#Example prompts

The following example prompts demonstrate how you can use natural language to interact with your Hygraph project through the MCP server.

Content queries:

  • List all blog posts in Hygraph published this week.
  • Find all entries in Hygraph with status DRAFT that were last updated more than 90 days ago.

Content updates:

  • Find all posts in Hygraph with status DRAFT and update their priority to High.
  • Publish all entries in Hygraph currently in review.

Multi-step workflows:

  • Find all posts in Hygraph with urgent in the title, update their priority to High, then publish them.
  • Move all published entries in Hygraph to the staging environment.

Schema operations:

  • Show me the structure of the Product model in Hygraph .
  • Create a new model in Hygraph called Author with name, bio, and avatar fields.
  • Add a required SEO Title field to all models in Hygraph that represent pages.
  • Add a new enumeration in Hygraph called Priority with values Low, Medium, High.

Combined workflows:

  • List all blog posts from Hygraph and create individual Markdown files for each post with front matter including slug, title, and publish date.
  • Generate TypeScript types for all content models in Hygraph.

#Safety guardrails

The Hygraph MCP server is designed to prevent accidental data loss in automated workflows. The following operations are intentionally not supported via MCP and must be performed manually in Hygraph Studio:

  • Delete entries or schema elements
  • Unpublish entries

This ensures that AI-assisted workflows cannot unintentionally remove or revert production content or schema.

#Next steps

Ready to connect your AI assistant? See the MCP server setup guide.