create_or_update_consumer

Create or update a consumer in APISIX with username, description, labels, and plugins via the APISIX-MCP server, ensuring accurate consumer management.

Instructions

Create a consumer, if the consumer already exists, it will be updated

Input Schema

TableJSON Schema

Name	Required	Description
`desc`	No	consumer description
`group_id`	No	consumer group id
`labels`	No	consumer labels
`plugins`	No	consumer plugins
`username`	Yes	consumer username

Implementation Reference

src/schemas/consumer.ts:5-14 (schema)

Defines the ConsumerSchema (Zod schema) which is aliased as CreateOrUpdateConsumerSchema and used for input validation of the tool.

export const ConsumerSchema = z
  .object({
    username: z.string().describe("consumer username"),
    desc: z.string().optional().describe("consumer description"),
    labels: z.record(z.string(), z.string()).optional().describe("consumer labels"),
    plugins: PluginSchema.optional().describe("consumer plugins"),
    group_id: z.string().optional().describe("consumer group id"),
  })
  .passthrough()
  .describe("consumer configuration object");

src/tools/consumer.ts:6-13 (registration)

Registers the "create_or_update_consumer" tool on the MCP server with description, input schema, and inline async handler function.

server.tool(
  "create_or_update_consumer",
  "Create a consumer, if the consumer already exists, it will be updated",
  CreateOrUpdateConsumerSchema.shape,
  async (args) => {
    return await makeAdminAPIRequest(`/consumers`, "PUT", args);
  }
);

src/tools/consumer.ts:6-13 (handler)

The server.tool call includes the handler lambda that executes the tool logic by calling makeAdminAPIRequest.

server.tool(
  "create_or_update_consumer",
  "Create a consumer, if the consumer already exists, it will be updated",
  CreateOrUpdateConsumerSchema.shape,
  async (args) => {
    return await makeAdminAPIRequest(`/consumers`, "PUT", args);
  }
);

src/utils/adminAPI.ts:11-80 (helper)

Supporting utility function makeAdminAPIRequest that performs the HTTP request to the APISIX Admin API using axios and formats the response as CallToolResult.

export async function makeAdminAPIRequest(
  path: string,
  method: string = "GET",
  data?: object
): Promise<CallToolResult> {
  const baseUrl = `${APISIX_SERVER_HOST}:${APISIX_ADMIN_API_PORT}${APISIX_ADMIN_API_PREFIX}`;
  const url = `${baseUrl}${path}`;

  try {
    const response = await axios({
      method,
      url,
      data,
      headers: {
        "X-API-KEY": APISIX_ADMIN_KEY,
        "Content-Type": "application/json",
      },
    });

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(response.data, null, 2),
        },
      ],
    };
  } catch (error) {
    if (axios.isAxiosError(error)) {
      console.error(`Request failed: ${method} ${url}`);
      console.error(
        `Status: ${error.response?.status}, Error: ${error.message}`
      );

      if (error.response?.data) {
        try {
          const stringifiedData = JSON.stringify(error.response.data);
          console.error(`Response data: ${stringifiedData}`);
        } catch {
          console.error(`Response data: [Cannot parse as JSON]`);
        }
      }

      return {
        isError: true,
        content: [
          {
            type: "text",
            text: JSON.stringify(
              `Status: ${error.response?.status}\nMessage: ${error.message}
Data:\n${JSON.stringify(error.response?.data || {}, null, 2)}`,
              null,
              2
            ),
          },
        ],
      };
    } else {
      return {
        isError: true,
        content: [
          {
            type: "text",
            text: JSON.stringify(error, null, 2),
          },
        ],
      };
    }
  }
}

APISIX-MCP