Advanced Hasura GraphQL MCP Server

Instructions

Implementation Reference

• src/index.ts:130-142 (handler)

  The main execution logic for the 'run_graphql_query' tool: logs execution, checks for mutation, executes the query using makeGqlRequest helper, returns formatted JSON result or throws error.

  async ({ query, variables }) => {
    console.log(`[INFO] Executing tool 'run_graphql_query'`);
    if (query.trim().toLowerCase().startsWith('mutation')) {
        throw new Error("This tool only supports read-only queries...");
    }
    try {
      const result = await makeGqlRequest(query, variables);
      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
    } catch (error: any) {
       console.error(`[ERROR] Tool 'run_graphql_query' failed: ${error.message}`);
       throw error;
    }
  }

• src/index.ts:126-129 (schema)

  Zod input schema defining the tool parameters: required 'query' (string) and optional 'variables' (object).

  {
    query: z.string().describe("The GraphQL query string (must be a read-only operation)."),
    variables: z.record(z.unknown()).optional().describe("Optional. An object containing variables..."),
  },

• src/index.ts:123-143 (registration)

  The MCP server.tool() registration call for 'run_graphql_query', including description, input schema, and inline handler function.

  server.tool(
    "run_graphql_query",
    "Executes a read-only GraphQL query against the Hasura endpoint...",
    {
      query: z.string().describe("The GraphQL query string (must be a read-only operation)."),
      variables: z.record(z.unknown()).optional().describe("Optional. An object containing variables..."),
    },
    async ({ query, variables }) => {
      console.log(`[INFO] Executing tool 'run_graphql_query'`);
      if (query.trim().toLowerCase().startsWith('mutation')) {
          throw new Error("This tool only supports read-only queries...");
      }
      try {
        const result = await makeGqlRequest(query, variables);
        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
      } catch (error: any) {
         console.error(`[ERROR] Tool 'run_graphql_query' failed: ${error.message}`);
         throw error;
      }
    }
  );

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

  Supporting utility function that performs the actual GraphQL request using GraphQLClient, merges headers (including admin secret), and handles ClientError with GraphQL-specific error messages.

  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;
    }
  }