Advanced Hasura GraphQL MCP Server

Instructions

Implementation Reference

• src/index.ts:145-165 (registration)

  Registration of the 'run_graphql_mutation' tool with the MCP server, specifying name, description, input schema using Zod, and the handler function.

  server.tool(
    "run_graphql_mutation",
    "Executes a GraphQL mutation to insert, update, or delete data...",
    {
      mutation: z.string().describe("The GraphQL mutation string."),
      variables: z.record(z.unknown()).optional().describe("Optional. An object containing variables..."),
    },
    async ({ mutation, variables }) => {
      console.log(`[INFO] Executing tool 'run_graphql_mutation'`);
      if (!mutation.trim().toLowerCase().startsWith('mutation')) {
          throw new Error("The provided string does not appear to be a mutation...");
      }
      try {
        const result = await makeGqlRequest(mutation, variables);
        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
      } catch (error: any) {
        console.error(`[ERROR] Tool 'run_graphql_mutation' failed: ${error.message}`);
        throw error;
      }
    }
  );

• src/index.ts:152-164 (handler)

  The core handler function that validates the mutation query, executes it via makeGqlRequest helper, returns formatted JSON result as MCP content, and propagates errors.

  async ({ mutation, variables }) => {
    console.log(`[INFO] Executing tool 'run_graphql_mutation'`);
    if (!mutation.trim().toLowerCase().startsWith('mutation')) {
        throw new Error("The provided string does not appear to be a mutation...");
    }
    try {
      const result = await makeGqlRequest(mutation, variables);
      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
    } catch (error: any) {
      console.error(`[ERROR] Tool 'run_graphql_mutation' failed: ${error.message}`);
      throw error;
    }
  }

• src/index.ts:148-151 (schema)

  Input schema using Zod: required 'mutation' string parameter and optional 'variables' object for GraphQL variables.

  {
    mutation: z.string().describe("The GraphQL mutation string."),
    variables: z.record(z.unknown()).optional().describe("Optional. An object containing variables..."),
  },

• src/index.ts:54-74 (helper)

  Helper function to execute GraphQL requests with the configured gqlClient, merging headers, handling variables, and providing detailed error messages for GraphQL and client errors.

  async function makeGqlRequest<
      T = any,
      V extends Record<string, any> = Record<string, any>
  >(
    query: string,
    variables?: V,
    requestHeaders?: Record<string, string>
  ): Promise<T> {
    try {
      const combinedHeaders = { ...headers, ...requestHeaders };
      return await gqlClient.request<T>(query, variables, combinedHeaders);
    } catch (error) {
      if (error instanceof ClientError) {
        const gqlErrors = error.response?.errors?.map(e => e.message).join(', ') || 'Unknown GraphQL error';
        console.error(`[ERROR] GraphQL Request Failed: ${gqlErrors}`, error.response);
        throw new Error(`GraphQL operation failed: ${gqlErrors}`);
      }
      console.error("[ERROR] Unexpected error during GraphQL request:", error);
      throw error;
    }
  }