Integrating MCP V2

Firefly MCP Server — Setup & Integration Guide

AWS Bedrock AgentCore MCP Gateway

Overview

What Is It?

The Firefly MCP Server is an AWS Bedrock AgentCore MCP Gateway service that enables AI agents — such as Claude Code, Cursor, and Claude Desktop — to access Firefly backend APIs in a secure, standardized way.

AI agents authenticate using a Firefly Access Key and Secret Key. A Lambda interceptor handles credential exchange, converting these keys into a short-lived JWT that is transparently attached to every forwarded request.

The gateway is automatically synced with the latest Firefly API specs.

How It Works

• AI Agent → AgentCore MCP Gateway → Lambda Interceptor (JWT exchange) → Firefly Backend API

• Agent sends x-access-key and x-secret-key headers.

• Lambda exchanges credentials for JWT (cached until expiry).

• JWT is added as Authorization: Bearer header.

• Request is forwarded to the backend API.

Step 1 — Create API Keys

Before configuring any client, you need an API Key pair. You can use an existing key pair or generate a new one.

Use Existing Key Pair

Enter your Access Key and Secret Key in the provided fields. If you already have a Firefly API key pair (for example, from Settings → Access Management), you can use it here.

Generate New Key Pair

Generate a new API Key pair directly from the MCP integration page:

1. In the Key Type dropdown, choose one of:

   • User API Key — Creates a new API key associated with your user account.

   • Service Account API Key — Creates a new API key associated with a service account. Select the desired service account from the list, then use New API Key to create the key for that account.

2. Click New API Key (or complete the flow for the selected key type). Your ACCESS KEY and SECRET KEY will be displayed after the keypair is created.

Important: When generating a new key, save your Secret Key immediately. Once you close the dialog, the Secret Key cannot be retrieved again. Store it securely in a password manager or secrets vault.

MCP configuration

No matter which method you choose—existing key pair or newly generated (User or Service Account)—the MCP configuration snippet on the page is automatically updated with your Access Key and Secret Key. You can copy that snippet into Cursor, Claude Code, or Claude Desktop as described in the steps below.

Step 2 — Choose Your MCP Endpoint

The Firefly MCP Server is available in two regions. Use the endpoint that matches the region your Firefly app is hosted in:

• US — https://mcpv2.firefly.ai/mcp (app at app.firefly.ai)

• EU — https://mcpv2.eu.firefly.ai/mcp (app at app.eu.firefly.ai)

Note: The X-access-Key / X-secret-Key headers are identical for both regions. In the client setup steps below, replace <YOUR_MCP_ENDPOINT> with the endpoint for your region.

Cursor Setup

Open mcp.json

Locate and open your mcp.json configuration file.

Add the MCP Server Configuration

Insert the following JSON block, replacing the placeholder values with your credentials:

"mcpServers": {
  "firefly-mcp": {
    "type": "http",
    "url": "<YOUR_MCP_ENDPOINT>",
    "headers": {
      "X-access-Key": "YOUR_ACCESS_KEY_HERE",
      "X-secret-Key": "YOUR_SECRET_KEY_HERE"
    }
  }
}

Restart Cursor

Save the file and restart Cursor.

Verify the Installation

Go to Settings → Tools and MCP. Under Installed MCP Servers you should see firefly-mcp.

Claude Code Setup

Add the MCP Server

Run the following command in a terminal, replacing the placeholder values with your credentials:

claude mcp add --transport http firefly-mcp <YOUR_MCP_ENDPOINT> \
  --header "X-access-Key: YOUR_ACCESS_KEY_HERE" \
  --header "X-secret-Key: YOUR_SECRET_KEY_HERE"

Verify the Installation

claude mcp list

firefly-mcp should appear in the output.

Codex Setup

The OpenAI Codex CLI connects to the Firefly MCP Server over streamable HTTP. You can add it by editing config.toml directly or by using the codex mcp add command.

Note: Remote (HTTP) MCP servers require a recent version of Codex CLI. Check your version with codex --version and upgrade if needed (e.g. npm install -g @openai/codex@latest).

Option A — Edit config.toml (recommended)

Open config.toml

Locate and open ~/.codex/config.toml in a text editor. Create the file if it does not already exist.

Add the MCP Server Configuration

Add the following block, replacing the placeholder values with your credentials:

[mcp_servers.firefly-mcp]
url = "<YOUR_MCP_ENDPOINT>"
http_headers = { "X-access-Key" = "YOUR_ACCESS_KEY_HERE", "X-secret-Key" = "YOUR_SECRET_KEY_HERE" }

To keep your credentials out of the config file, set them as environment variables and reference them with env_http_headers instead. Codex resolves each header value from the named environment variable at runtime:

[mcp_servers.firefly-mcp]
url = "<YOUR_MCP_ENDPOINT>"
env_http_headers = { "X-access-Key" = "FIREFLY_ACCESS_KEY", "X-secret-Key" = "FIREFLY_SECRET_KEY" }

Option B — Use the Codex CLI

If your Codex version does not yet support remote HTTP servers, you can connect through the mcp-remote bridge, which runs as a local stdio server. This mirrors the Claude Desktop setup below and requires npx (Node.js).

Run the following command in a terminal, replacing the placeholder values with your credentials:

codex mcp add firefly-mcp -- npx mcp-remote <YOUR_MCP_ENDPOINT> \
  --header "X-access-Key: YOUR_ACCESS_KEY_HERE" \
  --header "X-secret-Key: YOUR_SECRET_KEY_HERE"

Verify the Installation

Start Codex and run /mcp in the TUI to list active MCP servers. firefly-mcp should appear. You can also confirm the entry was written to ~/.codex/config.toml.

Claude Desktop Setup

Prerequisites

• npx must be installed on your machine. npx is included with Node.js. We recommend installing the latest version of Node.js. Verify by running npx --version in a terminal.

Open Claude Desktop Settings

Press your user avatar in the bottom left corner and select Settings.

Navigate to the Developers Tab

Go to the Developers tab and click Edit Config. A new window will open the Claude configuration directory.

Edit the Configuration File

Open claude_desktop_config.json with a text editor and add the following:

{
  "mcpServers": {
    "firefly-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "<YOUR_MCP_ENDPOINT>",
        "--header",
        "X-access-Key: YOUR_ACCESS_KEY_HERE",
        "--header",
        "X-secret-Key: YOUR_SECRET_KEY_HERE"
      ]
    }
  }
}

Restart Claude Desktop

Save the changes and restart Claude Desktop.

Verify the Installation

Go to Settings → Developers tab. Under Local MCP servers you should see firefly-mcp.

Limitations

Note: The tools presented in any connected client may not reflect the full set of available tools exposed by the Firefly MCP Server. There is a limitation to show only 30 tools.