Miraga MCP Setup Guide for ChatGPT, Claude Code, Claude Desktop, Cursor, Trae, WorkBuddy, and OpenClaw

Overview

Miraga MCP lets your AI coding assistant talk directly to Miraga's generation and workflow APIs. Instead of manually switching between browser tabs, prompts, task pages, and model settings, your agent can create images, start videos, check task status, inspect supported models, and calculate credits from one connected tool layer.

This guide explains the complete product flow: how to create and manage your Miraga API key, what each Miraga MCP tool is for, how to connect Miraga in ChatGPT (Codex), Claude Code, Claude Desktop, Cursor, WorkBuddy, Trae, and OpenClaw, and how to verify that everything is working before you rely on it in production workflows.

Who This Guide Is For

• Developers: who want Miraga generation inside coding agents such as Claude Code, Cursor, Trae, or OpenClaw.
• Operators and PMs: who want agents to check model support, task status, and credits from business tools like WorkBuddy or ChatGPT.
• Creative teams: who want a stable, revocable API key model instead of relying on browser sessions.

What You Get With Miraga MCP

• Unified access: Connect one MCP server and let your agent use Miraga tools without custom scripts.
• Authenticated generation: Your API key maps back to your Miraga account and credits.
• Async task handling: Start image and video tasks, then query task state from the same agent session.
• Model and price visibility: Ask your agent which models are available and how many credits a run will cost.
• Safer account control: You can create separate API keys for different clients and revoke them any time.

Create Your API Key

1. Sign in to your Miraga account.
2. Open My Profile.
3. Find the new API Key Management card.
4. Enter a descriptive name such as Claude Code, Trae, or OpenClaw.
5. Optionally set an expiration time. Leave it empty if you want the key to stay active until you manually delete it.
6. Click Create API Key.
7. Copy the raw key immediately and store it in your password manager or local secret storage.

Important: Miraga only shows the full API key once. After you close the success panel, the key cannot be viewed again. The dashboard keeps only a secure hash plus management metadata such as creation time, expiration time, and last usage time.

Manage and Revoke Keys

The API Key Management panel is designed for normal product operations, not just developer setup.

• Create a separate key per client: for example one for Claude Code, one for ChatGPT, and one for Trae.
• Use expiration dates: especially when you are testing, sharing temporary access, or configuring a team environment.
• Review usage: the list shows last used time so you can see which integrations are actually active.
• Delete compromised keys: if a machine is lost, a config file is exposed, or a teammate no longer needs access, delete that key and create a new one.

What Each Miraga MCP Tool Does

When you connect Miraga MCP, your client can expose a tool set like the following:

• generate_image: create a new image or perform image editing with a prompt, model, optional input images, and aspect ratio settings.
• get_image_generation_task: check the status of an async image task and retrieve the generated image when it completes.
• generate_video: start an image-to-video or text-to-video generation task through the same backend used by the Miraga web app.
• get_generation_task: query video task status, progress, and final result URL.
• rewrite_prompt: ask Miraga to improve or transform prompts before generation.
• list_models: inspect currently supported image and video models.
• get_model_detail: fetch a specific model configuration by model ID.
• calculate_price: estimate credit cost before running a job.
• check_credits: verify whether the account has enough credits for a requested operation.
• get_credit_balance: return the account's current credit balance.

This means your agent can do more than send one-shot prompts. It can reason about model choice, estimate budget, submit work, and poll task results without you leaving the current coding session.

How Authentication Works

Miraga MCP accepts either a normal Miraga web JWT or a Miraga API key. For most desktop agent products, the API key is the better choice because it is stable, revocable, and purpose-built for MCP access.

Behind the scenes, Miraga validates your API key, checks whether it exists and whether it is expired, and then converts it into a short-lived authenticated session for downstream Miraga services. That design keeps the MCP server lightweight while preserving the same permission model used by the main product.

Server Endpoint

Use your Miraga MCP endpoint, for example:

https://mcp.vmiraga.com/

Authentication header format:

Authorization: Bearer YOUR_MIRAGA_API_KEY

Copyable Configuration Template

Many MCP clients use a remote server configuration that looks conceptually similar to the following:

{
  "name": "miraga",
  "transport": "http",
  "url": "https://mcp.vmiraga.com/",
  "headers": {
    "Authorization": "Bearer YOUR_MIRAGA_API_KEY"
  }
}

If your client uses a different field name such as serverUrl, endpoint, authHeaders, or bearerToken, map the same values into that UI.

Client Setup Pattern

Different agent products label MCP fields differently, but the setup pattern is usually the same:

1. Create a new MCP server or tool connection.
2. Set the server URL to your Miraga MCP endpoint.
3. Add an Authorization header using your Miraga API key.
4. Save the configuration.
5. Approve the client trust, tool permission, or prompt trust dialog if the agent asks for it.
6. Ask the client to refresh or reconnect the server.
7. Verify by calling a safe read tool such as get_credit_balance or list_models.

ChatGPT (Codex)

ChatGPT environments that support MCP or tool connectors usually present a server form for remote tools.

{
  "name": "miraga",
  "url": "https://mcp.vmiraga.com/",
  "headers": {
    "Authorization": "Bearer YOUR_MIRAGA_API_KEY"
  }
}

1. Open the tools, connectors, or MCP settings in your ChatGPT environment.
2. Create a new remote MCP server.
3. Set the URL to https://mcp.vmiraga.com/.
4. Add the header Authorization: Bearer YOUR_MIRAGA_API_KEY.
5. Save and reconnect.
6. If ChatGPT asks whether to trust or approve the MCP server and its tools, choose Trust or Allow.
7. Test with a request like: List Miraga image and video models.

Best use case: fast product operations, prompt rewriting, model inspection, and generation without leaving the conversation.

Claude Code

Claude Code is especially useful when you want your coding agent to make Miraga calls while editing project files, scripts, prompt templates, or creative automation flows.

{
  "mcpServers": {
    "miraga": {
      "url": "https://mcp.vmiraga.com/",
      "headers": {
        "Authorization": "Bearer YOUR_MIRAGA_API_KEY"
      }
    }
  }
}

1. Open Claude Code MCP settings.
2. Add a new remote server named miraga.
3. Use https://mcp.vmiraga.com/ as the server URL.
4. Add the Authorization bearer header with your Miraga API key.
5. If Claude Code shows a trust or tool approval prompt for the new server, approve it before testing.
6. Reconnect and run a validation request.

Best use case: developer-centric workflows where code, assets, prompts, and generation tasks need to stay in the same working session.

Claude Desktop

Claude Desktop is a strong fit when you want a conversational desktop assistant with tool access, but without the full IDE context of Claude Code.

1. Open the Claude Desktop MCP or connectors configuration.
2. Add Miraga as a remote MCP server.
3. Use https://mcp.vmiraga.com/ as the endpoint.
4. Paste your Miraga API key into the Authorization bearer header field.
5. If Claude Desktop asks you to trust the server or allow its tools, approve that prompt first.
6. Restart or reconnect Claude Desktop so the tool manifest is reloaded.

Best use case: non-IDE users who still want rich Miraga actions such as prompt rewriting, model lookup, price estimation, and task polling inside a desktop AI workspace.

Cursor

Cursor is useful when your team wants code-aware assistance plus direct access to Miraga generation services in the same editor.

{
  "mcpServers": {
    "miraga": {
      "url": "https://mcp.vmiraga.com/",
      "headers": {
        "Authorization": "Bearer YOUR_MIRAGA_API_KEY"
      }
    }
  }
}

1. Open Cursor's MCP or tools integration settings.
2. Create a new remote MCP server named miraga.
3. Set the URL to https://mcp.vmiraga.com/.
4. Add Authorization: Bearer YOUR_MIRAGA_API_KEY.
5. If Cursor asks whether to trust the MCP server or allow tool access, confirm it before continuing.
6. Reconnect and ask Cursor to list available Miraga models.

Best use case: shipping prompt libraries, creative tooling, automation scripts, or application code that needs direct Miraga integration from the editor.

Trae

Trae works well when you want an IDE-native assistant that can reason about your project while also using Miraga as an external generation backend.

{
  "mcpServers": {
    "miraga": {
      "url": "https://mcp.vmiraga.com/",
      "headers": {
        "Authorization": "Bearer YOUR_MIRAGA_API_KEY"
      }
    }
  }
}

1. Open MCP server settings inside Trae.
2. Add a new remote MCP endpoint.
3. Set the endpoint URL to https://mcp.vmiraga.com/.
4. Add your Authorization bearer header.
5. If Trae shows a trust confirmation for the new MCP server, approve it so the tools can be used.
6. Refresh the tool list and confirm that Miraga tools appear.

Best use case: integrating Miraga generation with content systems, product code, prompt libraries, templates, and internal automation flows.

WorkBuddy

WorkBuddy usually sits closer to business workflows, operator tasks, and structured multi-step execution.

1. Open the integrations or MCP configuration area.
2. Create a Miraga MCP connection.
3. Use the Miraga endpoint and API key bearer header.
4. If WorkBuddy shows a trust, authorization, or tool approval dialog for the MCP connection, approve it first.
5. Save the connection and trigger a simple test call.

Best use case: operations teams that need repeatable media generation, prompt workflows, task tracking, or account-level budget awareness.

OpenClaw

OpenClaw-style agent environments are attractive for users who want flexible open workflows and their own orchestration layer.

{
  "mcpServers": {
    "miraga": {
      "url": "https://mcp.vmiraga.com/",
      "headers": {
        "Authorization": "Bearer YOUR_MIRAGA_API_KEY"
      }
    }
  }
}

1. Add Miraga as a remote MCP server.
2. Configure the endpoint URL and Authorization header.
3. If OpenClaw asks you to trust the new MCP server or enable its tools, approve that request.
4. Reload the client so the Miraga tool manifest is fetched again.
5. Use a read-only tool first to confirm the connection.

Best use case: teams or advanced users building custom AI pipelines with external tools, internal prompts, and their own agent orchestration patterns.

Validation Checklist

Before you start real production runs, validate the connection in this order:

1. Connectivity: confirm the MCP server is reachable.
2. Trust prompt: confirm the client has marked the Miraga MCP server as trusted or approved for tool use.
3. Authentication: run get_credit_balance or list_models.
4. Permissions: confirm the returned data matches the correct Miraga account.
5. Async flow: create an image task with generate_image in async mode, then query it with get_image_generation_task.
6. Video flow: optionally submit a short video task and verify get_generation_task works as expected.
7. Budget awareness: ask the agent to run calculate_price before generation.

Simple Verification Commands

After setup, these are good first tests to run in any client:

• Connection test: "List Miraga image and video models."
• Account test: "Check my Miraga credit balance."
• Pricing test: "Calculate the credit cost for a 10-second 720p video with model X."
• Async image test: "Create an async image task, then poll it until the image is ready."

Recommended Prompt Patterns

• For discovery: Ask the agent to list supported models and recommend one for your goal.
• For safe execution: Ask for a price estimate before generation.
• For image iteration: Start with async image generation so the agent can poll without blocking.
• For multi-step pipelines: Rewrite prompt, calculate price, generate asset, then fetch task result.

Security Best Practices

• Do not paste API keys into shared chats or screenshots.
• Use separate keys per tool: this makes revocation easy and usage easier to track.
• Set expiration for temporary experiments: especially on shared machines.
• Delete unused keys: if you no longer use a client, remove its key from Miraga.
• Store keys in secret managers: prefer built-in credential stores over plain text notes.

When To Use Miraga MCP Instead of the Web UI

The Miraga web app remains the best place for visual browsing, direct manual creation, and account administration. Miraga MCP becomes the better choice when you want the agent itself to participate in the workflow: editing prompts, selecting models, checking costs, submitting tasks, and pulling results into the same development or operator context.

FAQ

Do I need a separate API key for every client?

You do not have to, but it is strongly recommended. Separate keys make revocation, auditing, and environment isolation much easier.

Can I use the same Miraga account credits through MCP?

Yes. Miraga MCP maps your API key back to your Miraga account, so tool calls use the same account context and credits.

What happens if an API key expires?

The MCP connection will stop authenticating successfully. Create a new key or extend your operational process by rotating keys before their expiration date.

Can I delete a key without affecting the website?

Yes. Deleting an MCP API key only revokes that key. Your standard website login flow remains unchanged.

Which tools should I use first after connecting?

Start with list_models and get_credit_balance, then move to calculate_price, and only then start image or video generation tasks.

Final Recommendation

If your team already works inside AI-native coding or operations tools, Miraga MCP turns Miraga into a proper production service layer instead of a browser-only destination. Create a dedicated API key for each client, connect the MCP endpoint once, validate with read-only tools first, and then let your agent take over the repetitive parts of generation workflow.