> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fapihub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Agents (MCP)

> Let AI agents remove backgrounds and edit your local images with the FAPIHub MCP server.

The open-source [FAPIHub MCP server](https://github.com/Firdavs-coder/fapihub-mcp) lets AI agents use the FAPIHub API on files on your computer. It works with Claude Code, Claude Desktop, Cursor, VS Code and Windsurf.

Once it's installed, ask your agent in plain language:

* "Remove the background from assets/product.jpg"
* "Put every photo in ./team on a #F5F5F5 background"
* "How many FAPIHub requests do I have left?"

Results are saved next to the input as `<name>_<operation>.png`. The server never overwrites an existing file.

### Install

**1. Install uv**

The server runs with [`uv`](https://docs.astral.sh/uv/). Install it if you don't have it yet.

**2. Get an API key**

Create an API key in the [dashboard](https://fapihub.com/dashboard/). Keys look like `bg_live_sk_…`.

**3. Add the server to your agent**

**Claude Code**

```bash theme={null}
claude mcp add fapihub -s user -e FAPIHUB_API_KEY=bg_live_sk_... -- uvx --from git+https://github.com/Firdavs-coder/fapihub-mcp fapihub-mcp
```

`-s user` makes the server available in every project. Without it, the server is added to the current project only.

**Verify:** start a new Claude Code session and run `/mcp`. `fapihub` should show as connected with 7 tools.

**Remove:**

```bash theme={null}
claude mcp remove fapihub -s user
```

**Claude Desktop**

Open **Settings → Developer → Edit Config**. This opens `claude_desktop_config.json`:

* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
* Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Add the server, with the **full path** to `uvx` in `"command"`:

```json theme={null}
{
  "mcpServers": {
    "fapihub": {
      "command": "/Users/you/.local/bin/uvx",
      "args": ["--from", "git+https://github.com/Firdavs-coder/fapihub-mcp", "fapihub-mcp"],
      "env": { "FAPIHUB_API_KEY": "bg_live_sk_..." }
    }
  }
}
```

> [!WARNING]
>
> Desktop apps on macOS often don't inherit your shell `PATH`, so a bare `"command": "uvx"` fails with `spawn uvx ENOENT`. Find the full path with `which uvx` (macOS/Linux) or `where uvx` (Windows). It's usually `~/.local/bin/uvx`, but write it out in full (for example `/Users/you/.local/bin/uvx`) because `~` doesn't work in JSON.

After saving, fully quit Claude Desktop and reopen it.

**Cursor**

Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json theme={null}
{
  "mcpServers": {
    "fapihub": {
      "command": "/Users/you/.local/bin/uvx",
      "args": ["--from", "git+https://github.com/Firdavs-coder/fapihub-mcp", "fapihub-mcp"],
      "env": { "FAPIHUB_API_KEY": "bg_live_sk_..." }
    }
  }
}
```

> [!WARNING]
>
> Use the full path to `uvx` in `"command"`. Find it with `which uvx` (macOS/Linux) or `where uvx` (Windows); `~` doesn't work in JSON.

**Verify:** in **Settings → MCP**, `fapihub` should show as connected.

**VS Code**

Add the server to `.vscode/mcp.json`. The top-level key is `servers`, not `mcpServers`:

```json theme={null}
{
  "servers": {
    "fapihub": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Firdavs-coder/fapihub-mcp", "fapihub-mcp"],
      "env": { "FAPIHUB_API_KEY": "bg_live_sk_..." }
    }
  }
}
```

Use the server from Copilot Chat in **Agent** mode.

**Windsurf**

Add the server to `~/.codeium/windsurf/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "fapihub": {
      "command": "/Users/you/.local/bin/uvx",
      "args": ["--from", "git+https://github.com/Firdavs-coder/fapihub-mcp", "fapihub-mcp"],
      "env": { "FAPIHUB_API_KEY": "bg_live_sk_..." }
    }
  }
}
```

> [!WARNING]
>
> Use the full path to `uvx` in `"command"`. Find it with `which uvx` (macOS/Linux) or `where uvx` (Windows); `~` doesn't work in JSON.

**4. Try it**

Ask your agent: "Remove the background from assets/product.jpg".

### Test without an AI

Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to check the server on its own:

```bash theme={null}
FAPIHUB_API_KEY=bg_live_sk_... npx @modelcontextprotocol/inspector uvx --from git+https://github.com/Firdavs-coder/fapihub-mcp fapihub-mcp
```

1. Open the URL it prints.
2. Click **Connect**.
3. Open **Tools** and choose `get_usage`.
4. Click **Run**. You should see your plan and remaining requests. `get_usage` is free.

### Tools

| Tool | Does | Options |
| - | - | - |
| `remove_background` | Transparent cutout | `model` |
| `create_mask` | Subject mask | `model` |
| `blur_background` | Blurs the background | `radius` (1–50, default 10) |
| `color_background` | Solid color background | `color` |
| `gradient_background` | Vertical gradient background | `top_color`, `bottom_color` |
| `add_shadow` | Drop shadow | `shadow_color`, `offset_x`, `offset_y`, `blur_radius` |
| `get_usage` | Plan, limits, used/remaining | — (free) |

* Each image tool takes `image_path` and an optional `output_path`.
* Colors can be hex (`#FF8C00`) or RGB(A) (`255, 140, 0`).

### Environment variables

| Variable | Required | Default | Description |
| - | - | - | - |
| `FAPIHUB_API_KEY` | Yes | — | Your FAPIHub API key |
| `FAPIHUB_BASE_URL` | No | `https://fapihub.com` | API base URL |
| `FAPIHUB_TIMEOUT` | No | `120` | Request timeout in seconds |

### Quota

* Each image tool call uses one request from your quota. `get_usage` is free.
* Invalid inputs (missing file, wrong format, wrong size) are caught locally before anything is sent, so they don't use quota.

See [Rate Limit](https://docs.fapihub.com/rate-limit.md) for your plan's limits.

### Troubleshooting

> **spawn uvx ENOENT / the server won't start**
>
> Use the full path to `uvx` in `"command"` (find it with `which uvx` or `where uvx`), or install [uv](https://docs.astral.sh/uv/) first.

> **"FAPIHUB\_API\_KEY is not set"**
>
> Add the key to the `env` block of your config, or to the `-e` flag in Claude Code.

> **"Authentication failed … Check FAPIHUB\_API\_KEY"**
>
> The key is wrong or deactivated. Create a new one in the [dashboard](https://fapihub.com/dashboard/).

> **"Monthly request limit reached …" (402)**
>
> Your quota is used up. Check it with `get_usage`, and upgrade at [fapihub.com/billing](https://fapihub.com/billing/).

> **"Rate limit exceeded. Retry after N seconds."**
>
> Wait N seconds, then try again. Retrying is free.

> **The tools don't appear**
>
> Fully restart the app or start a new session. The server is loaded only at startup.

### Updates

`uvx` fetches the latest version from GitHub. To force an update, run `uv cache clean fapihub-mcp` or restart the app.

> **[fapihub-mcp on GitHub](https://github.com/Firdavs-coder/fapihub-mcp)**
>
> Source code, issues and the latest install instructions.

> [!NOTE]
>
> **Not the same as the docs MCP server.** Mintlify also hosts an MCP server for this documentation at `https://docs.fapihub.com/mcp`. It lets AI tools search these docs; it doesn't process images. To edit images, use the FAPIHub MCP server above.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.