# MCP server & tools

> Add Figgshield as an MCP connector in Claude or the Claude Code CLI, the five tools (generate_image, generate_video, get_generation, list_library, get_usage), example prompts, config JSON and OAuth discovery.

Figgshield is a remote **MCP server** — a single Streamable HTTP endpoint that Claude and the Claude Code CLI call to generate video and images. It implements the MCP spec `2025-11-25` (with `2025-06-18` compatibility).

| Item | Value |
| --- | --- |
| MCP endpoint | `https://api.figgshield.ai/mcp` |
| Transport | Streamable HTTP (`POST` / `GET` / `DELETE`) |
| Auth | OAuth 2.1 (browser sign-in) **or** `Authorization: Bearer figg_...` API key |
| Models | Kling (video), Nano Banana 2 (image) |

## Add Figgshield to Claude

### Claude Desktop or claude.ai

1. Open **Settings → Connectors**.
2. Choose **Add custom connector**.
3. Paste the endpoint `https://api.figgshield.ai/mcp` and save.
4. Claude opens a browser sign-in. Sign in with Google, Apple or GitHub and approve the scopes `figgshield:read` and `figgshield:write`.

The connector is registered automatically (Dynamic Client Registration), so there is nothing to configure by hand. Tokens refresh on their own; you will not be asked to sign in again unless you revoke access.

### Claude Code CLI

```bash
claude mcp add --transport http figgshield https://api.figgshield.ai/mcp
claude mcp login figgshield
```

`claude mcp login` runs a browser sign-in (loopback PKCE) and stores the token. Full details, and the API-key alternative, are in [Claude Code CLI](https://figgshield.ai/documentation/cli.md).

### Config JSON

Clients that read an MCP config file (for example `claude_desktop_config.json`) can declare Figgshield directly:

```json
{
  "mcpServers": {
    "figgshield": {
      "type": "http",
      "url": "https://api.figgshield.ai/mcp"
    }
  }
}
```

On first use the client runs the OAuth flow above. To use an API key instead of the browser flow, add a header:

```json
{
  "mcpServers": {
    "figgshield": {
      "type": "http",
      "url": "https://api.figgshield.ai/mcp",
      "headers": { "Authorization": "Bearer figg_your_api_key_here" }
    }
  }
}
```

## Tools

Figgshield exposes five tools. The two generate tools spend credits (with auto top-up if enabled) and state the model they used; the other three are read-only.

### `generate_image`

Runs **Nano Banana 2**. Burns **8 credits**.

| Param | Type | Notes |
| --- | --- | --- |
| `prompt` | string | What to generate. Required. |
| `resolution` | string | Optional. `"1K"`, `"2K"` or `"4K"` (default `"1K"`). |

Returns `{ generation_uuid, model: "Nano Banana 2", status, output_url?, credits_charged }`.

### `generate_video`

Runs **Kling**. Burns **35 credits** for a 5-second clip; **70** for 10 seconds or with audio.

| Param | Type | Notes |
| --- | --- | --- |
| `prompt` | string | What to generate. Required. |
| `duration` | integer | Optional. `5` or `10` seconds (default `5`). |
| `resolution` | string | Optional. `"720p"` or `"1080p"` (default `"720p"`). |
| `audio` | boolean | Optional. Default `false`; `true` doubles the credit cost. |

Returns `{ generation_uuid, model: "Kling", status, output_url?, credits_charged }`.

### `get_generation`

Polls a job to completion. Read-only.

| Param | Type | Notes |
| --- | --- | --- |
| `generation_uuid` | string | The id returned by a generate tool. Required. |

Returns `{ status, output_url?, error? }`. `status` is `queued`, `running`, `succeeded` or `failed`.

### `list_library`

Recent generations, newest first. Read-only.

| Param | Type | Notes |
| --- | --- | --- |
| `limit` | integer | Optional. How many to return. |
| `kind` | string | Optional. `"video"` or `"image"` to filter. |

Returns `[{ uuid, model, kind, prompt, status, output_url, created_at }]`.

### `get_usage`

Current plan and credit balance. Read-only. Returns `{ plan, credits: { balance, granted_this_period, used_this_period }, jobs }`.

## Example prompts

Once connected, ask Claude in plain language — it picks the tool and the model:

```text
Generate a 5-second video of a quiet harbour at dawn, mist lifting off the water.
Make a 10-second clip with audio of rain on a city street at night.
Create a 2K image of a paper boat on a still pond, top-down.
Show my last five generations.
How many credits do I have left this month?
```

## Credit checks and errors

Each generate tool runs a **pre-flight credit check**. If your balance cannot cover the job it surfaces as a tool error: `insufficient_credits` (top up or enable auto top-up) or `subscription_required` (no active plan). With [auto top-up](https://figgshield.ai/documentation/billing.md) enabled, the top-up is attempted first. Failed generations are refunded automatically.

## OAuth discovery

Figgshield is an OAuth 2.1 resource server with a co-hosted authorization server; PKCE (S256) is required and Google/Apple/GitHub are the upstream identity providers. An unauthenticated `/mcp` request returns `401` with a `WWW-Authenticate: Bearer resource_metadata="..."` header pointing at the protected-resource metadata. Clients discover the rest from these documents:

| Document | URL |
| --- | --- |
| Protected resource metadata (RFC 9728) | `https://api.figgshield.ai/.well-known/oauth-protected-resource` |
| Authorization server metadata (RFC 8414) | `https://api.figgshield.ai/.well-known/oauth-authorization-server` |
| OpenID configuration | `https://api.figgshield.ai/.well-known/openid-configuration` |
| JWKS | `https://api.figgshield.ai/jwks.json` |

Claude performs this discovery for you. See [Authentication](https://figgshield.ai/documentation/authentication.md) for the token flow and the API-key alternative.