Grok MCP Server

Instructions

Implementation Reference

• src/operations/chat.ts:233-242 (handler)

  The core handler function that executes the tool logic by sending a POST request to the Grok API's chat/completions endpoint using the grokRequest helper and parsing the response with Zod.

  export async function createChatCompletion(
    options: z.infer<typeof ChatCompletionRequestSchema>
  ): Promise<z.infer<typeof ChatCompletionSchema>> {
    const response = await grokRequest("chat/completions", {
      method: "POST",
      body: options,
    });
  
    return ChatCompletionSchema.parse(response);
  }

• src/operations/chat.ts:139-230 (schema)

  The Zod input schema (ChatCompletionRequestSchema) defining the parameters for the create_chat_completion tool, used in both the handler type and tool registration.

  export const ChatCompletionRequestSchema = z.object({
    model: z.string().describe("ID of the model to use"),
    messages: z
      .array(MessageSchema)
      .describe("Messages to generate chat completions for"),
    tools: z
      .array(ToolSchema)
      .optional()
      .describe("List of tools the model may call"),
    tool_choice: z
      .union([
        z.literal("auto"),
        z.literal("none"),
        z.object({
          type: z.literal("function"),
          function: z.object({
            name: z
              .string()
              .describe("Force the model to call the specified function"),
          }),
        }),
      ])
      .optional()
      .describe("Controls which (if any) tool is called by the model"),
    temperature: z
      .number()
      .min(0)
      .max(2)
      .optional()
      .describe("Sampling temperature (0-2)"),
    top_p: z
      .number()
      .min(0)
      .max(1)
      .optional()
      .describe("Nucleus sampling parameter (0-1)"),
    n: z
      .number()
      .int()
      .positive()
      .optional()
      .describe("Number of chat completion choices to generate"),
    stream: z
      .boolean()
      .optional()
      .describe("If set, partial message deltas will be sent"),
    max_tokens: z
      .number()
      .int()
      .positive()
      .optional()
      .describe("Maximum number of tokens to generate"),
    presence_penalty: z
      .number()
      .min(-2)
      .max(2)
      .optional()
      .describe("Penalty for new tokens based on presence in text (-2 to 2)"),
    frequency_penalty: z
      .number()
      .min(-2)
      .max(2)
      .optional()
      .describe("Penalty for new tokens based on frequency in text (-2 to 2)"),
    logit_bias: z
      .record(z.string(), z.number())
      .optional()
      .describe(
        "Map of token IDs to bias scores (-100 to 100) that influence generation"
      ),
    response_format: z
      .object({ type: z.enum(["text", "json_object"]) })
      .optional()
      .describe(
        "Specify 'json_object' to receive JSON response or 'text' for raw text"
      ),
    seed: z
      .number()
      .int()
      .optional()
      .describe(
        "If specified, results will be more deterministic when the same seed is used"
      ),
    stop: z
      .union([z.string(), z.array(z.string())])
      .optional()
      .describe("Sequences where the API will stop generating further tokens"),
    user: z.string().optional().describe("A unique user identifier"),
    search_parameters: SearchParametersSchema.optional().describe(
      "Parameters for live search capabilities"
    ),
  });

• index.ts:97-122 (registration)

  The FastMCP tool registration for 'create_chat_completion', linking the input schema and handler execute function.

  server.addTool({
    name: "create_chat_completion",
    description: "Create a chat completion with the Grok API",
    parameters: chat.ChatCompletionRequestSchema,
    execute: async (args) => {
      try {
        console.error(
          `[DEBUG] Creating chat completion with model: ${args.model}`
        );
        const completion = await chat.createChatCompletion(args);
        console.error(`[DEBUG] Chat completion created successfully`);
        return JSON.stringify(completion, null, 2);
      } catch (err) {
        console.error(`[ERROR] Failed to create chat completion:`, err);
        if (err instanceof GrokResourceNotFoundError) {
          throw new Error(
            `Model '${args.model}' not found. Please verify:\n` +
              `1. The model exists\n` +
              `2. You have correct access permissions\n` +
              `3. The model name is spelled correctly`
          );
        }
        handleError(err);
      }
    },
  });