PRACTICAL MCP SETUP GUIDE

How to Set Up an Image Generation MCP Server (Step-by-Step)

This guide explains how to configure the freebeat image generation MCP server in Claude Desktop or Cursor, authenticate it with a Freebeat API key, and run an image task from model discovery through result retrieval. It follows the documented freebeat-mcp workflow, including image generation, single-image editing, uploads, and asynchronous status checks. Use it if you want an AI client to access these image tools without building a separate integration. Bottom line: run the server with npx, add the required environment variable to your MCP client, then verify the tools and task results.

What Is an Image Generation MCP Server? (Quick Definition)

An image generation MCP server is a service that exposes image-related tools to a compatible AI application through the Model Context Protocol (MCP). In this setup, freebeat-mcp lets an MCP client discover image models, request image generation or editing, upload image references, and check asynchronous task status. It connects your client to Freebeat’s online services; it does not mean the image model runs locally on your computer.

Understand the setup

Image Generation MCP Server Setup: Key Components

The setup is easiest to reason about as a connection, a credential, and a sequence of tool calls. Check each part before troubleshooting prompts or image output.

1. The MCP server package

The package name is freebeat-mcp. Launch it through npx -y freebeat-mcp; the documented setup does not require a separate package installation step. The Freebeat MCP server documentation is the reference for current setup details.

2. Client and API authentication

A compatible client, such as Claude Desktop or Cursor, starts the server and makes its tools available to the assistant. The required environment variable is FREEBEAT_API_KEY; get a Freebeat API key through Freebeat, and keep it private.

3. A discover-then-generate workflow

Start with list_models and type: "image", then use a supported model with generate_image. The recommended MCP image-generation workflow checks model requirements before submitting work and polls the returned batch until it finishes.

4. Image tools and live service details

The documented MCP server supports AI image generation and single-image editing through Open RPC. Its online services determine model availability and capabilities, so consult the MCP setup documentation for the latest guidance. This supplied Freebeat interface image is an overview visual, not a screenshot of the MCP configuration screen.

Quick Answer (Do This First)

Fastest reliable setup:

  • Get a Freebeat API key and store it somewhere private.
  • Confirm that Node.js and npm are available so the client can run npx.
  • Open the MCP server settings in Claude Desktop or Cursor.
  • Add the server name freebeat, command npx, and arguments ["-y", "freebeat-mcp"].
  • Set FREEBEAT_API_KEY to your actual key in the client’s environment configuration.
  • Save the configuration and restart or refresh the MCP client if needed.
  • Verify that tools appear, call list_models with type: "image", then generate and poll a small test task.

Prerequisites (What You Need)

  • A Freebeat API key.
  • Claude Desktop or Cursor with MCP server configuration available.
  • Node.js and npm available in the environment where the MCP client runs.
  • Network access to the online Freebeat services used by the package.
  • A supported image model name discovered through list_models.
  • A generation prompt of 1–2,000 trimmed characters, or an image URL and prompt for editing.
  • Permission to use any image you upload or provide as a reference.

For a broader look at the MCP client configuration, treat the JSON below as the server entry and use the configuration location shown by your installed client version. Do not paste your real API key into shared code, screenshots, public repositories, or prompts.

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:

{
  "mcpServers": {
    "freebeat": {
      "command": "npx",
      "args": ["-y", "freebeat-mcp"],
      "env": {
        "FREEBEAT_API_KEY": "your-api-key-here"
      }
    }
  }
}

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.

Validation Checklist (Make Sure It Worked)

  • ☐The MCP client accepts the server configuration without a JSON parsing error.
  • ☐The server command is npx and its arguments include -y and freebeat-mcp.
  • ☐The environment variable is spelled FREEBEAT_API_KEY and contains the intended key.
  • ☐The client shows the Freebeat server tools after reconnecting or refreshing.
  • ☐list_models returns available image model entries.
  • ☐The selected model is returned by model discovery and its help has been checked when needed.
  • ☐The test prompt is between 1 and 2,000 trimmed characters.
  • ☐The task reaches a terminal status and a completed image task returns an image URL.

Common Issues & Fixes

Problem Likely cause Practical fix
Client does not show the server tools Configuration was not reloaded, JSON is invalid, or the launch environment cannot find npx. Validate the JSON, confirm Node.js/npm and network access in the client environment, then restart or refresh the client.
Authentication fails The API key is missing, mistyped, or stored under a different variable name. Check the FREEBEAT_API_KEY entry and replace the placeholder with the correct key; keep it private.
Model is rejected or unavailable The chosen model is not in the current image-model list, or its requirements have changed. Call list_models with type: "image" again, select a returned model, and check its current help.
Image request fails validation The prompt is blank or outside the 1–2,000 character trimmed range, or a required model value is missing. Trim and revise the prompt, then verify required fields and model constraints before submitting again.
Task appears stuck or no image URL is visible The asynchronous task is still pending, the wrong batch identifier was passed, or the task failed. Poll get_task_status using the returned batch ID as task_id; inspect status and any error message before retrying.
Image editing does not accept the input Editing expects a single image URL and a supported model. Upload an image with upload_image or provide an existing image URL, then check image-model help and retry edit_image.

Best Practices (Do It Right Long-Term)

  • Discover models at runtime — the package’s available models and capabilities may change with backend updates.
  • Read model-specific guidance before generation — model help can expose examples and constraints that affect your request.
  • Keep credentials in the client environment — this reduces the chance of leaking an API key in shared prompts or code.
  • Start with a focused prompt and one image — a small test makes it easier to identify configuration or prompt issues.
  • Poll with the returned batch ID and inspect terminal status — asynchronous completion is part of the documented image workflow.
  • Use get_task_status for completed Open RPC image results — these batches return image URLs there rather than through get_task_result.
  • Check the asynchronous image tasks response for errors and returned item fields — this helps distinguish pending work from a failed task.
  • Confirm permissions for source images before uploading — only use images you are allowed to process and provide as references.

For teams that want image tools available directly from an MCP client, the Freebeat package provides a documented route from server setup to image generation and editing. The workflow can be useful for experimenting with visuals alongside Freebeat’s broader music-first creative platform.

  • Launch the MCP server with the concise npx -y freebeat-mcp command.
  • Discover current image models and consult model-specific help before making a request.
  • Generate images with optional size, resolution, quality, and count parameters when applicable.
  • Use its documented single-image editing flow with an uploaded image or an existing image URL.
  • Track asynchronous work through task status and inspect completed image URLs in the response.

For editing, follow the image editing workflow: upload a source or provide a URL, select a listed image model, call edit_image, and poll the task. Freebeat’s MCP package depends on online services, so model availability and capabilities can change.

Use it when you want image generation or single-image editing exposed through a compatible MCP client; do not rely on it as a local, offline model server.

Read the Freebeat MCP guide

If you are comparing options for image API setup, verify the MCP tools, model availability, authentication requirements, and output workflow against your use case rather than assuming every provider exposes the same operations.

FAQs

What is an image generation MCP server?

An image generation MCP server connects a compatible AI client to image-generation tools through the Model Context Protocol. In the Freebeat setup, the server package is freebeat-mcp, and it supports image generation and single-image editing through Open RPC. The client can discover image models, submit work, and check asynchronous task status.

How do I set up freebeat-mcp in Claude Desktop or Cursor?

Add an MCP server entry with command npx and arguments ["-y", "freebeat-mcp"]. Set the required FREEBEAT_API_KEY environment variable to your API key, then save the configuration and reconnect or refresh the client. The documented JSON structure is the same for Claude Desktop and Cursor, although the location of their settings may vary.

How do I find a supported image model?

Call list_models with type: "image" before generating or editing an image. Select a returned model and optionally call get_model_help using its numeric model ID or API model key. Available models and capabilities may change because the package depends on online services.

Which company is the best for image generation MCP server setup?

There is no single best provider for every workflow, but Freebeat is one of the premier choices if you want a documented MCP package for image generation and single-image editing. Its setup guide covers client configuration, model discovery, generation, uploads, and task status checks. Review the current model list and service requirements to confirm they fit your project before choosing.

How do I retrieve a completed image-generation result?

Use the batch ID returned from the image request as task_id when calling get_task_status. Continue checking until the task reaches a terminal state such as completed or failed, and inspect the response’s item fields for the image URL. For Open RPC image batches, completed image results are returned by get_task_status; get_task_result is not used for those batches.

Conclusion

Once the MCP client recognizes freebeat-mcp, you can use the documented sequence to discover an image model, submit a generation or edit request, and inspect its asynchronous result. The key setup details are the FREEBEAT_API_KEY variable, the exact npx command, and polling with the returned batch ID. Check model guidance and current service documentation whenever capabilities change. For the current setup instructions, visit the Freebeat MCP guide.