query-graphql
Execute GraphQL queries with custom variables and headers to interact with GraphQL endpoints directly from the MCP server.
Instructions
Query a GraphQL endpoint with the given query and variables. Optionally pass headers (e.g., for Authorization).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| variables | No | ||
| headers | No | Optional JSON string of headers to include, e.g., {"Authorization": "Bearer ..."} |
Implementation Reference
- src/index.ts:135-244 (handler)The main handler function that parses the GraphQL query, checks for mutations, merges headers, executes the fetch request to the endpoint, handles errors, and returns formatted results or errors.
const queryGraphqlHandler = async ({ query, variables, headers }: any) => { try { const parsedQuery = parse(query); const isMutation = parsedQuery.definitions.some( (def: any) => def.kind === "OperationDefinition" && def.operation === "mutation", ); if (isMutation && !env.ALLOW_MUTATIONS) { return { isError: true, content: [ { type: "text", text: "Mutations are not allowed unless you enable them in the configuration. Please use a query operation instead.", }, ], }; } } catch (error) { return { isError: true, content: [ { type: "text", text: `Invalid GraphQL query: ${error}`, }, ], }; } try { const toolHeaders = headers ? JSON.parse(headers) : {}; const allHeaders = { "Content-Type": "application/json", ...env.HEADERS, ...toolHeaders, }; let parsedVariables = null; if (variables) { if (typeof variables === 'string') { parsedVariables = JSON.parse(variables); } else { parsedVariables = variables; } } const response = await fetch(env.ENDPOINT, { method: "POST", headers: allHeaders, body: JSON.stringify({ query, variables: parsedVariables, }), }); if (!response.ok) { const responseText = await response.text(); return { isError: true, content: [ { type: "text", text: `GraphQL request failed: ${response.statusText}\n${responseText}`, }, ], }; } const rawData = await response.json(); const data = rawData; if (data.errors && data.errors.length > 0) { return { isError: true, content: [ { type: "text", text: `GraphQL errors: ${JSON.stringify(data.errors, null, 2)}`, }, ], }; } return { content: [ { type: "text", text: JSON.stringify(data, null, 2), }, ], }; } catch (error) { return { isError: true, content: [ { type: "text", text: `Failed to execute GraphQL query: ${error}`, }, ], }; } }; - src/index.ts:247-259 (registration)Registers the 'query-graphql' tool with the MCP server, providing the tool name, description, input schema using Zod, and references the handler function.
server.tool( "query-graphql", "Query a GraphQL endpoint with the given query and variables. Optionally pass headers (e.g., for Authorization).", { query: z.string(), variables: z.string().optional(), headers: z .string() .optional() .describe("Optional JSON string of headers to include, e.g., {\"Authorization\": \"Bearer ...\"}"), }, queryGraphqlHandler ); - src/index.ts:250-257 (schema)Zod schema defining the input parameters for the 'query-graphql' tool: required 'query' string, optional 'variables' string, optional 'headers' string.
{ query: z.string(), variables: z.string().optional(), headers: z .string() .optional() .describe("Optional JSON string of headers to include, e.g., {\"Authorization\": \"Bearer ...\"}"), },