# Flatkey MCP

> Independently maintained by [mguozhen](https://github.com/mguozhen) for Flatkey API users. This is not yet a `flatkey-ai` organization release.

Use Flatkey from any MCP-compatible AI client. The server lists the models enabled for your Flatkey account, checks credits and status, and can generate text, images, video, speech, sound effects, and music.

Each generation tool is explicitly marked as credit-consuming so compatible clients can ask for confirmation before a paid request is sent.

## Install

You need Node.js 20+ and a Flatkey API key from [flatkey.ai/keys](https://flatkey.ai/keys).

### Codex

```bash
codex mcp add flatkey \
  --env FLATKEY_API_KEY=YOUR_FLATKEY_API_KEY \
  -- npx -y @mguozhen/flatkey-mcp@1.0.0
```

### Claude Code

```bash
claude mcp add --transport stdio flatkey \
  --env FLATKEY_API_KEY=YOUR_FLATKEY_API_KEY \
  -- npx -y @mguozhen/flatkey-mcp@1.0.0
```

### Generic MCP JSON

```json
{
  "mcpServers": {
    "flatkey": {
      "command": "npx",
      "args": ["-y", "@mguozhen/flatkey-mcp@1.0.0"],
      "env": {
        "FLATKEY_API_KEY": "YOUR_FLATKEY_API_KEY"
      }
    }
  }
}
```

Keep your API key out of source control and public support requests.

## Tools

| Tool | What it does | Credits |
| --- | --- | --- |
| `flatkey_list_models` | Lists models enabled for the account, optionally by type | No |
| `flatkey_get_credits` | Shows remaining credit balance | No |
| `flatkey_get_status` | Shows account/service usage status | No |
| `flatkey_generate_text` | Generates text with a selected Flatkey model | Yes |
| `flatkey_generate_image` | Creates an image | Yes |
| `flatkey_generate_video` | Creates a video request | Yes |
| `flatkey_generate_speech` | Creates text-to-speech audio | Yes |
| `flatkey_generate_sound_effect` | Creates a sound effect | Yes |
| `flatkey_generate_music` | Creates music | Yes |

Call `flatkey_list_models` before selecting a model. The available inventory can differ by account.

## Configuration

| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `FLATKEY_API_KEY` | Yes | — | API key used only to call Flatkey |
| `FLATKEY_BASE_URL` | No | `https://router.flatkey.ai` | Gateway override for development/testing |
| `FLATKEY_MODELS_BASE_URL` | No | `https://console.flatkey.ai` | Model registry override for development/testing |

## Development

```bash
npm install
npm test
npm run lint
npm run pack:check
```

Routine tests use a mocked gateway; they do not spend Flatkey credits.

## Security

- The MCP server receives the API key only through `FLATKEY_API_KEY`; it is never accepted as a tool argument.
- Tool errors are sanitized and never include an Authorization header.
- The generation tools can consume credits and are marked as destructive/paid actions for client confirmation.

## Catalog metadata

`server.json` is the canonical manifest for the Official MCP Registry and compatible catalogs. `CATALOG_COPY.md` contains the listing copy. Do not submit the manifest until `@mguozhen/flatkey-mcp@1.0.0` and the `mguozhen/flatkey-mcp` repository are public: registries validate that install target.