Grid MCP Server

A simple Model Context Protocol (MCP) server that provides access to the Grid GraphQL API at https://beta.node.thegrid.id/graphql.

Features

• Two Tools:
  • query - Execute custom GraphQL queries against the Grid API
  • find - Flexible search for products or assets by name, type, and/or status with powerful query syntax
• No Authentication: Direct access to the public Grid endpoint
• TypeScript: Fully typed implementation
• npx Ready: No installation required, works via npx

Installation

No installation required! Just add to your MCP client configuration.

Cursor IDE

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "grid": {
      "command": "npx",
      "args": ["-y", "@the-grid-data/mcp@latest"]
    }
  }
}

Claude Desktop

macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "grid": {
      "command": "npx",
      "args": ["-y", "@the-grid-data/mcp@latest"]
    }
  }
}

Restart your MCP client after making changes.

MCP Tools

1. query

Execute a custom GraphQL query against the Grid API.

How to use: Just ask Claude in natural language to query the Grid API.

Examples:

Query The Grid MCP to get the first 5 profiles with their id and slug

Use The Grid MCP to fetch all product types

Can you run this GraphQL query:
query {
  products(limit: 10) {
    id
    name
  }
}

2. find

Flexible search for products or assets with powerful filtering capabilities.

How to use: Just ask Claude to find products or assets using natural language. The AI will automatically handle the filtering logic.

What you can search by:

• Entity type (products or assets)
• Name (exact match or partial search)
• Type (exact match or multiple types)
• Status (exact match or multiple statuses)
• Limit the number of results

Examples:

Basic searches:

Find all L1 products on The Grid

Search for assets with "bitcoin" in the name on The Grid

Show me products with type L1, L2, or L3 on The Grid

Multiple filters:

Find active products with names containing "wallet"

Get L1 and L2 products that are either active or pending status

Show me the first 20 assets with "ethereum" in the name

Advanced:

Find products where type is either L1 or contains "Layer", and status is active

Search for pending or active L2 products, limit to 5 results

What you get back: List of products/assets with id, name, type, status, and associated root

How It Works

This MCP server uses stdio transport - it runs locally on your machine when invoked by Claude Desktop or other MCP clients. No hosting or HTTP server needed!

When you use npx, it:

1. Downloads and caches the package on first use
2. Runs it locally when Claude needs to query the Grid API
3. Communicates via stdin/stdout with the MCP client

GraphQL Endpoint

The server proxies requests to: https://beta.node.thegrid.id/graphql

No authentication required.

Architecture

Claude Desktop → stdio → The Grid MCP (local npx) → HTTP → Grid GraphQL API

Troubleshooting

MCP server not showing up in Claude/Cursor

1. Check configuration file location:

   • Cursor: ~/.cursor/mcp.json
   • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json

2. Verify JSON syntax: Ensure your configuration is valid JSON (no trailing commas, proper quotes)

3. Restart completely: Fully quit and restart the application (not just reload window)

4. Check logs:

   • Cursor: Check the Developer Tools console (Help → Toggle Developer Tools)
   • Claude Desktop: Check application logs for MCP connection errors

"Tool not found" errors

If Claude says it can't find the find or query tools:

1. Restart the MCP server in your client settings
2. Verify the server is running: check MCP status in your client
3. Clear any cached configurations and restart

GraphQL query errors

If you get parsing errors from the GraphQL API:

1. Verify field names: Ensure you're using correct field names for the Grid API schema
2. Check query syntax: The find tool generates valid syntax, but custom query tool requires valid GraphQL
3. Use query tool for debugging: Try the raw query tool to test GraphQL directly

Connection or network errors

1. Verify endpoint: The server connects to https://beta.node.thegrid.id/graphql
2. Check network: Ensure your machine can reach the Grid API
3. Firewall/proxy: Check if corporate firewall or proxy is blocking the connection

Development issues

1. Build fails: Run npm install or pnpm install to ensure dependencies are installed
2. TypeScript errors: Ensure you're using TypeScript 5.3.3 or higher
3. Module resolution: This package uses ES modules ("type": "module" in package.json)

Still having issues?

• Check the GitHub Issues for similar problems
• Review the MCP protocol documentation at modelcontextprotocol.io
• Ensure you're using the latest version: npx @the-grid-data/mcp@latest

Contributing

For development setup and contribution guidelines, see the GitHub repository.

License

MIT