Step-by-Step: Set Up the Image Generation MCP Server
Step 1: Get your API key and protect it
Obtain a Freebeat API key through the Freebeat site. Store it in a secure place while preparing the client configuration; the server reads it from the FREEBEAT_API_KEY environment variable.
Success looks like: You have a valid key ready to add to the MCP client, without placing it in a public file or message.
Common mistake to avoid: Leaving the example text your-api-key-here unchanged in the final configuration.
Step 2: Confirm the client can run the package
Use a compatible MCP client such as Claude Desktop or Cursor. Make sure Node.js/npm and network access are available in the environment that launches the client, because the documented command runs the package through npx.
Success looks like: The client environment can resolve the npx command and reach online services.
Common mistake to avoid: Testing npm in a different environment than the one used by the desktop client.
Step 3: Add the server configuration
In the MCP configuration area for your client, add a server called freebeat. The documented configuration shape is the same for Claude Desktop and Cursor:
Success looks like: The configuration is valid JSON and includes the command, arguments, and environment variable.
Common mistake to avoid: Adding trailing commas or changing the package name, which can prevent the client from starting the server.
Step 4: Set the environment variable
Replace the placeholder value with your API key in the client’s local configuration. Keep the variable name exactly as documented: FREEBEAT_API_KEY.
Success looks like: The key is present in the server environment and the server entry remains valid JSON.
Common mistake to avoid: Using a different variable name, adding spaces to the key, or exposing the secret in shared logs.
Step 5: Save the configuration and reconnect
Save the MCP settings. Restart or refresh the client if it does not automatically reload the server entry, then check the client’s available MCP tools for Freebeat functions.
Success looks like: The client recognizes the Freebeat server and exposes its available tools.
Common mistake to avoid: Troubleshooting generation calls before confirming the server is connected and its tools are visible.
Step 6: Discover an image model and check its guidance
Call list_models with type: "image". Choose a returned model and, when useful, call get_model_help with its numeric model_id or API model key to review examples and constraints. This image model discovery step avoids guessing model identifiers.
Success looks like: You have a valid image model and know any model-specific requirements relevant to your request.
Common mistake to avoid: Hard-coding an assumed model name instead of selecting from the current response.
Step 7: Generate an image and poll the batch
Call generate_image with the selected model and a descriptive prompt. The prompt must be 1–2,000 characters after trimming. Optional fields include size, resolution, quality, and count; count defaults to 1. For GPT-Image 2 (model ID 108), omitted quality and resolution default to medium and 1024x1024. If resolution is omitted and size is supplied, the server also sends size as resolution for compatibility.
Success looks like: The request returns a batch ID that you can use to check task status and retrieve image URLs when complete.
Common mistake to avoid: Sending an empty, overlong, or whitespace-only prompt; follow the prompt constraints and inspect model help before retrying.
Step 8: Check status and inspect the result
Poll get_task_status with the returned batch_id supplied as task_id. For an Open RPC image batch, you may also pass serial_no to check one item. Look for a terminal status such as completed or failed; completed image batches include image URLs in the status response, with fields such as image_url or edit_images.
Success looks like: The task reaches a terminal status and, when completed, the response contains an image result.
Common mistake to avoid: Calling get_task_result for an Open RPC image batch; its completed image results are returned directly by get_task_status.