- [Claude Code](#claude-code)
- [Claude connector](#claude-connector)
- [Cursor IDE](#cursor-ide)
- [VS Code](#vs-code)
- [Windsurf IDE](#windsurf-ide)
- [Claude Desktop (PAT)](#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.
```bash
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.
```bash
claude mcp add hygraph https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp \
--transport http \
--header "Authorization: Bearer YOUR_HYGRAPH_TOKEN"
```
**Scope options:**
| Flag | Effect |
|------------------|-----------------------------|
| `--scope local` | This project only (default) |
| `--scope user` | All your projects |
| `--scope global` | System-wide |
**Verify the setup:**
```bash
# 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](#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](https://claude.ai/directory/hygraph-mcp).
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.
**Note:**
On Team and Enterprise plans, an Owner may need to add the connector under **Organization settings > Connectors** before members can connect. Ask your Claude admin if you don't see Hygraph MCP in the directory.
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](https://hygraph.com/docs/hygraph-ai/mcp-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](https://hygraph.com/docs/editor-guides/ai-tools/connect-ai-assistants-editors). It walks through the same connector from a non-technical angle.
### Cursor IDE
**Note:**
Cursor's default **Auto** model mode is not compatible with the Hygraph MCP server. You must select a model manually before using MCP tools.
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
```json
{
"mcpServers": {
"hygraph": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp",
"--header",
"Authorization: Bearer YOUR_TOKEN_HERE"
]
}
}
}
```
- **Global:** Add to your user-level `~/.cursor/mcp.json` file.
```json
{
"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"
}
}
}
}
```
### VS Code
VS Code has built-in MCP support. Add the following to `.vscode/mcp.json`:
```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`:
```json
{
"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](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
### Windsurf IDE
1. Go to **Windsurf Settings → Cascade → MCP Servers → Add Server**.
2. In `~/.codeium/windsurf/mcp_config.json`, add:
```json
{
"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"
}
}
}
}
```
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](#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:
```json
{
"mcpServers": {
"hygraph": {
"command": "npx",
"args": [
"mcp-remote@latest",
"https://mcp-{REGION}.hygraph.com/{PROJECT_ID}/{ENVIRONMENT}/mcp",
"--header",
"Authorization: Bearer YOUR_HYGRAPH_TOKEN"
]
}
}
}
```
3. Quit and reopen Claude Desktop.
**Note:**
If you manage Node versions with NVM or similar tools, ensure your active Node version is `>= 22` when launching 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.
```json
{
"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](#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.
[Video](https://www.youtube.com/watch?v=8730GGrYdng)
## 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](https://hygraph.com/docs/api-reference/basics/authorization#public-api-permissions) and [Management API permissions](https://hygraph.com/docs/getting-started/access-and-permissions/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](#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:
```bash
which npx
```
Test `mcp-remote` directly:
```bash
npx -y mcp-remote@latest YOUR_ENDPOINT --header "Authorization: Bearer TOKEN"
```
**For Claude Code:**
```bash
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 [