### Install mcp-graphql via Smithery

Source: https://github.com/blurrah/mcp-graphql/blob/main/README.md

Automatically install mcp-graphql for Claude Desktop using the Smithery CLI. This command simplifies the installation process.

```bash
npx -y @smithery/cli install mcp-graphql --client claude
```

--------------------------------

### Configure mcp-graphql as a Managed MCP Server in Claude Desktop

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Example configuration for `claude_desktop_config.json` to set up mcp-graphql as a managed MCP server. This includes command, arguments, environment variables, and endpoint configuration.

```json
// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
{
  "mcpServers": {
    "mcp-graphql": {
      "command": "npx",
      "args": ["mcp-graphql"],
      "env": {
        "ENDPOINT": "https://api.example.com/graphql",
        "HEADERS": "{\"Authorization\": \"Bearer your-token\"}",
        "ALLOW_MUTATIONS": "false",
        "NAME": "example-api"
      }
    }
  }
}
```

--------------------------------

### Manually Install mcp-graphql in Claude

Source: https://github.com/blurrah/mcp-graphql/blob/main/README.md

Manually configure mcp-graphql within Claude by defining its command, arguments, and environment variables in a JSON configuration.

```json
{
    "mcpServers": {
        "mcp-graphql": {
            "command": "npx",
            "args": ["mcp-graphql"],
            "env": {
                "ENDPOINT": "http://localhost:3000/graphql"
            }
        }
    }
}
```

--------------------------------

### Run mcp-graphql with Basic Usage

Source: https://github.com/blurrah/mcp-graphql/blob/main/README.md

Execute mcp-graphql with a local GraphQL server endpoint. Ensure the ENDPOINT environment variable is set.

```bash
ENDPOINT=http://localhost:3000/graphql npx mcp-graphql
```

--------------------------------

### Run mcp-graphql with Local Schema File

Source: https://github.com/blurrah/mcp-graphql/blob/main/README.md

Specify a local GraphQL schema file for mcp-graphql to use by setting the SCHEMA environment variable to the file path.

```bash
ENDPOINT=http://localhost:3000/graphql SCHEMA=./schema.graphql npx mcp-graphql
```

--------------------------------

### Run mcp-graphql with Mutations Enabled

Source: https://github.com/blurrah/mcp-graphql/blob/main/README.md

Enable mutation operations in mcp-graphql by setting the ALLOW_MUTATIONS environment variable to true. Be cautious in production.

```bash
ENDPOINT=http://localhost:3000/graphql ALLOW_MUTATIONS=true npx mcp-graphql
```

--------------------------------

### List and Read MCP GraphQL Schema Resource

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Use the MCP client to list available resources and then read the GraphQL schema from its URI. The schema is returned as an SDL string.

```typescript
const resources = await client.listResources();
// resources.resources[0].uri === "http://localhost:4000/graphql"
// resources.resources[0].name === "graphql-schema"

const schemaResource = await client.readResource({
  uri: "http://localhost:4000/graphql",
});

// schemaResource.contents[0].text is the full SDL string
console.log(schemaResource.contents[0].text);
// type Query {
//   products: [Product!]!
// }
// type Product {
//   id: ID!
//   title: String!
//   price: Float!
// }
```

--------------------------------

### Run mcp-graphql with Custom Headers

Source: https://github.com/blurrah/mcp-graphql/blob/main/README.md

Configure mcp-graphql to use custom headers for requests by setting the HEADERS environment variable with a JSON string.

```bash
ENDPOINT=https://api.example.com/graphql HEADERS='{"Authorization":"Bearer token123"}' npx mcp-graphql
```

--------------------------------

### Run mcp-graphql with Remote Schema URL

Source: https://github.com/blurrah/mcp-graphql/blob/main/README.md

Configure mcp-graphql to use a schema file hosted at a URL by setting the SCHEMA environment variable to the URL.

```bash
ENDPOINT=http://localhost:3000/graphql SCHEMA=https://example.com/schema.graphql npx mcp-graphql
```

--------------------------------

### Raw JSON-RPC Communication with MCP Server (stdio)

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Demonstrates low-level integration with an MCP server using newline-delimited JSON-RPC 2.0 messages over stdio. This bypasses the SDK for direct protocol interaction.

```typescript
import { spawn } from "node:child_process";
import { createInterface } from "node:readline";

const server = spawn("node", ["dist/index.js"], {
  stdio: ["pipe", "pipe", "pipe"],
  env: { ...process.env, ENDPOINT: "http://localhost:4000/graphql" },
});

const rl = createInterface({ input: server.stdout });
rl.on("line", (line) => {
  const msg = JSON.parse(line);
  console.log("← Server:", JSON.stringify(msg, null, 2));
});

// 1. Initialize
server.stdin.write(JSON.stringify({
  jsonrpc: "2.0",
  method: "initialize",
  params: {
    protocolVersion: "2025-03-26",
    capabilities: {},
    clientInfo: { name: "raw-client", version: "1.0.0" },
  },
  id: 1,
}) + "\n");

// 2. Send initialized notification
server.stdin.write(JSON.stringify({
  jsonrpc: "2.0",
  method: "notifications/initialized",
}) + "\n");

// 3. Call introspect-schema tool
server.stdin.write(JSON.stringify({
  jsonrpc: "2.0",
  method: "tools/call",
  params: { name: "introspect-schema", arguments: {} },
  id: 2,
}) + "\n");
```

--------------------------------

### Introspect GraphQL Schema using MCP SDK

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Use the MCP TypeScript SDK to connect to the mcp-graphql server and introspect the GraphQL schema. Ensure the client is configured with the correct command and environment variables.

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["dist/index.js"],
  env: { ENDPOINT: "http://localhost:4000/graphql" },
});

const client = new Client({ name: "my-client", version: "1.0.0" });
await client.connect(transport);

const result = await client.callTool({
  name: "introspect-schema",
  arguments: {},
});

// result.content[0].text contains the SDL, e.g.:
// type Query {
//   user(id: ID!): User
//   users: [User!]!
// }
// type User {
//   id: ID!
//   name: String!
//   email: String!
// }
console.log(result.content[0].text);
```

--------------------------------

### Custom Server Name for mcp-graphql

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Set a custom server name for mcp-graphql using the NAME environment variable. This is useful for distinguishing multiple server instances.

```bash
NAME=my-api-server \
  ENDPOINT=http://localhost:3000/graphql \
  npx mcp-graphql
```

--------------------------------

### Enable Mutations in mcp-graphql

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Enable mutation operations in mcp-graphql by setting the ALLOW_MUTATIONS environment variable to true. Mutations are disabled by default for security.

```bash
ENDPOINT=http://localhost:3000/graphql \
  ALLOW_MUTATIONS=true \
  npx mcp-graphql
```

--------------------------------

### Use Local Schema File with mcp-graphql

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Configure mcp-graphql to use a local schema file instead of live introspection. Set the SCHEMA environment variable to the path of your .graphql file.

```bash
ENDPOINT=http://localhost:3000/graphql \
  SCHEMA=./schema.graphql \
  npx mcp-graphql
```

--------------------------------

### MCP Tool: query-graphql

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Executes a GraphQL query or mutation against the configured endpoint. It accepts the query string and optional variables, returning the full JSON response or a structured error.

```APIDOC
## Tool: query-graphql

### Description
Executes a GraphQL query or (if enabled) mutation against the configured endpoint. Accepts the query string and an optional JSON-serialized variables string. Returns the full JSON response on success, or a structured error payload if the request fails or the query is invalid.

### Arguments
- `query` (string) - Required - The GraphQL query or mutation string.
- `variables` (string) - Optional - JSON string of query variables.

### Response
- `content` (array) - An array containing the result. The first element's `text` field holds the JSON response or error payload.
```

--------------------------------

### Introspect Local GraphQL Schema File

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Reads a local `.graphql` schema file and returns its content as a string. Use this when the SCHEMA environment variable points to a local file path.

```typescript
import { introspectLocalSchema } from "./src/helpers/introspection.js";

const sdl = await introspectLocalSchema("./schema.graphql");
// Returns raw file content, e.g.:
// type Query {
//   hello: String!
// }
```

--------------------------------

### mcp-graphql with Bearer Token Authentication

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Configure mcp-graphql to use a Bearer token for authentication. The HEADERS environment variable must be a JSON string containing the Authorization header.

```bash
ENDPOINT=https://api.example.com/graphql \
  HEADERS='{"Authorization":"Bearer eyJhbGciOiJIUzI1NiJ9...' \
  npx mcp-graphql
```

--------------------------------

### Execute GraphQL Query with Variables using MCP SDK

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Execute a GraphQL query with variables using the MCP TypeScript SDK. The query and variables are passed as arguments to the callTool method.

```typescript
// Execute a query with variables
const queryResult = await client.callTool({
  name: "query-graphql",
  arguments: {
    query: "\n      query GetUser($id: ID!) {\n        user(id: $id) {\n          id\n          name\n          email\n        }\n      }\n    ",
    variables: JSON.stringify({ id: "42" }),
  },
});

// Successful response
// {
//   "data": {
//     "user": {
//       "id": "42",
//       "name": "Alice",
//       "email": "alice@example.com"
//     }
//   }
// }
console.log(queryResult.content[0].text);
```

--------------------------------

### Introspect Remote GraphQL Schema URL

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Fetches a schema SDL file from a remote URL. This is used when the SCHEMA environment variable is set to an HTTP or HTTPS URL.

```typescript
import { introspectSchemaFromUrl } from "./src/helpers/introspection.js";

const sdl = await introspectSchemaFromUrl(
  "https://cdn.example.com/api/schema.graphql"
);
console.log(sdl); // Raw SDL text from the remote file
```

--------------------------------

### Attempt GraphQL Mutation without Permissions

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Attempting to execute a mutation without enabling mutations via ALLOW_MUTATIONS=true will result in an error. The error message indicates that mutations are not allowed.

```typescript
// Attempting a mutation without ALLOW_MUTATIONS=true returns an error
const mutationResult = await client.callTool({
  name: "query-graphql",
  arguments: {
    query: "mutation DeleteUser($id: ID!) { deleteUser(id: $id) { id } }",
    variables: JSON.stringify({ id: "42" }),
  },
});
// mutationResult.isError === true
// mutationResult.content[0].text:
// "Mutations are not allowed unless you enable them in the configuration."
```

--------------------------------

### Introspect GraphQL Endpoint with Headers

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Helper function to send a GraphQL introspection query to a live endpoint. Supports authentication headers for secure endpoints. Returns schema as SDL.

```typescript
import { introspectEndpoint } from "./src/helpers/introspection.js";

// With no auth headers
const sdl = await introspectEndpoint("http://localhost:4000/graphql");
console.log(sdl); // "type Query { ... }"

// With authentication headers
const sdlWithAuth = await introspectEndpoint(
  "https://api.example.com/graphql",
  { Authorization: "Bearer my-token", "X-API-Key": "secret" }
);
```

--------------------------------

### MCP Tool: introspect-schema

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Retrieves the full GraphQL schema SDL from the configured endpoint. This tool is useful for LLMs to discover the schema when it's not already available.

```APIDOC
## Tool: introspect-schema

### Description
Retrieves the full GraphQL schema SDL from the configured endpoint (or static schema source). LLMs should call this tool first when the schema is not already available as a resource. Returns the schema as a plain-text SDL string.

### Arguments
- `query` (string) - Required - The GraphQL query string.
- `variables` (string) - Optional - JSON string of query variables.

### Response
- `content` (array) - An array containing the result. The first element's `text` field holds the SDL string.
```

--------------------------------

### Merge Base and Override Headers

Source: https://context7.com/blurrah/mcp-graphql/llms.txt

Merges base configuration headers with per-request override headers. Input headers can be a JSON string or an object, with overrides taking precedence.

```typescript
import { parseAndMergeHeaders } from "./src/helpers/headers.js";

const base = { "X-App-Name": "my-app", Authorization: "Bearer base-token" };

// Override with a JSON string (as an LLM might provide)
const merged = parseAndMergeHeaders(base, '{"Authorization":"Bearer override"}');
// { "X-App-Name": "my-app", "Authorization": "Bearer override" }

// Override with a plain object
const merged2 = parseAndMergeHeaders(base, { "X-Request-ID": "abc123" });
// { "X-App-Name": "my-app", "Authorization": "Bearer base-token", "X-Request-ID": "abc123" }
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.