# 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:

```json
"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:

```bash
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

```bash
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:

```json
{
  "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.