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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.firefly.ai/integrations/integrating-mcp-v2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.