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.

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": "https://mcpv2.firefly.ai/mcp",
    "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 https://mcpv2.firefly.ai/mcp \
  --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.

Claude Desktop Setup

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",
        "https://mcpv2.firefly.ai/mcp",
        "--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.