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

# Percify MCP server for Claude, ChatGPT, Cursor and Codex

> Connect Claude, ChatGPT, Cursor or Codex to the Percify MCP server at https://mcp.percify.io/mcp to make images, voices and talking avatar videos.

The Percify MCP server lets AI assistants and coding agents use your Percify account through the Model Context Protocol. Add `https://mcp.percify.io/mcp` to Claude, ChatGPT, Cursor, Claude Code or Codex, and the assistant can price and run image, video and voice models, make an avatar speak a script, and wait for the result. Claude signs in to your Percify account with OAuth; clients without a browser sign-in send a Percify API key.

## Server details

|             |                                                                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------------- |
| URL         | `https://mcp.percify.io/mcp`                                                                               |
| Transport   | Streamable HTTP, JSON-RPC 2.0 over `POST` (no server-sent event stream)                                    |
| Auth        | OAuth sign-in, or `Authorization: Bearer pk_live_…`                                                        |
| Tools       | 23                                                                                                         |
| Billing     | The connected account's credits, the same as the app and the REST API                                      |
| Server card | [mcp.percify.io/.well-known/mcp/server-card.json](https://mcp.percify.io/.well-known/mcp/server-card.json) |

Connections set up with the earlier URL `https://api.percify.io/v3/mcp` keep working.

## Which sign-in should I use?

| Client                                         | Sign-in                                                    |
| ---------------------------------------------- | ---------------------------------------------------------- |
| Claude (web, desktop) custom connector         | OAuth: sign in to Percify and click **Authorize**. No key. |
| ChatGPT developer mode                         | OAuth                                                      |
| Claude Code, Cursor, Codex CLI, your own agent | API key in the `Authorization` header                      |

API keys are created on the [developer page](https://app.percify.io/home/developer) and need a Scale or Ultra plan. See [Authentication](/percify/api-auth).

## Add Percify to your client

<Tabs>
  <Tab title="Claude">
    These steps follow [Claude's custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for individual Free, Pro and Max plans. Free plans can add one custom connector.

    <Steps>
      <Step title="Add the connector">
        In Claude, go to **Customize** > **Connectors**, click **+**, then **Add custom connector**. Paste `https://mcp.percify.io/mcp` as the remote MCP server URL and click **Add**. Leave the OAuth client fields in advanced settings empty.
      </Step>

      <Step title="Connect and sign in">
        Click **Connect**. A Percify sign-in page opens. Sign in, and on the screen that asks you to allow the connection, click **Authorize**.
      </Step>

      <Step title="Use it in a chat">
        Turn the connector on for a conversation with the **+** button at the lower left of the chat, then **Connectors**. Then ask, for example: "What would a 10 second lip-sync video cost with Percify?"
      </Step>
    </Steps>

    On Team and Enterprise plans, an Owner first adds the connector under **Organization settings** > **Connectors**; members then click **Connect** in **Customize** > **Connectors**.
  </Tab>

  <Tab title="ChatGPT">
    OpenAI's [developer mode guide](https://developers.openai.com/api/docs/guides/developer-mode) says developer mode is available on ChatGPT Pro, Plus, Business, Enterprise and Education accounts on the web, supports streaming HTTP MCP servers and OAuth.

    <Steps>
      <Step title="Turn on developer mode">
        In ChatGPT, open **Settings** > **Security and login** and turn on **Developer mode**. On Business and Enterprise, a workspace admin may need to allow it first.
      </Step>

      <Step title="Create the app">
        Create a developer-mode app for a remote MCP server, as OpenAI's guide describes. Use `https://mcp.percify.io/mcp` as the server URL and choose OAuth authentication.
      </Step>

      <Step title="Sign in to Percify">
        When ChatGPT opens the Percify sign-in, log in and click **Authorize**.
      </Step>
    </Steps>

    ChatGPT's menus change often; if a label differs, follow OpenAI's current guide.
  </Tab>

  <Tab title="Claude Code">
    Run this with your API key in `PERCIFY_API_TOKEN`:

    ```bash theme={"system"}
    claude mcp add --transport http percify https://mcp.percify.io/mcp \
      --header "Authorization: Bearer $PERCIFY_API_TOKEN"
    ```

    Then run `/mcp` inside Claude Code to check that `percify` is connected.
  </Tab>

  <Tab title="Cursor">
    Add the server to `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` in one project:

    ```json theme={"system"}
    {
      "mcpServers": {
        "percify": {
          "url": "https://mcp.percify.io/mcp",
          "headers": {
            "Authorization": "Bearer pk_live_your_key_here"
          }
        }
      }
    }
    ```

    Do not commit a project `mcp.json` that contains a key.
  </Tab>

  <Tab title="Codex CLI">
    Add this to `~/.codex/config.toml`. Codex reads the key from the environment variable you name:

    ```toml theme={"system"}
    [mcp_servers.percify]
    url = "https://mcp.percify.io/mcp"
    bearer_token_env_var = "PERCIFY_API_TOKEN"
    ```

    Export `PERCIFY_API_TOKEN` in the shell that starts Codex.
  </Tab>
</Tabs>

Any other MCP client that can send a header works the same way: point it at `https://mcp.percify.io/mcp` and send `Authorization: Bearer pk_live_…` on every request.

## What tools does the Percify MCP server have?

Read-only tools are marked read-only in their MCP annotations, so clients can approve them without asking. Tools that spend credits are not.

### Models and generations

| Tool                  | What it does                                                                 | Spends credits |
| --------------------- | ---------------------------------------------------------------------------- | -------------- |
| `list_models`         | Lists models with id, output type, credit cost and required inputs           | No             |
| `get_model`           | One model's input schema, pricing and an example                             | No             |
| `estimate_cost`       | Exact credit price of a generation, without running it                       | No             |
| `generate`            | Starts a generation on any model                                             | Yes            |
| `get_generation`      | Reads a generation's status and output                                       | No             |
| `wait_for_generation` | Waits on the server until a generation ends, up to about 45 seconds per call | No             |
| `list_generations`    | Recent generations, newest first, with status, outputs and credits           | No             |
| `check_usage`         | Remaining credits, this month's spend and runs, and the top-up link          | No             |

### Avatar personas

| Tool             | What it does                                                                                          | Spends credits |
| ---------------- | ----------------------------------------------------------------------------------------------------- | -------------- |
| `create_avatar`  | Saves a reusable persona from a face image and a voice sample, or imports one of your Percify avatars | No             |
| `list_avatars`   | Lists your saved personas                                                                             | No             |
| `avatar_say`     | Makes a persona speak a script: cloned voice, then lip-sync video                                     | Yes            |
| `get_avatar_job` | Reads an `avatar_say` job; a finished job includes a preview image                                    | No             |
| `delete_avatar`  | Permanently deletes a persona and its job history                                                     | No             |

Attaching a voice with `create_avatar` requires `voiceConsent: true`, which only you can confirm. The assistant should ask you before setting it.

### Short videos

| Tool           | What it does                                                                                     | Spends credits |
| -------------- | ------------------------------------------------------------------------------------------------ | -------------- |
| `make_video`   | Writes a script from a topic, generates a presenter and voice, lip-syncs and edits a short video | Yes            |
| `reedit_video` | Re-cuts a finished `make_video` job with another edit style, reusing its lip-sync                | Yes            |
| `get_mascot`   | Reads a `make_video` job, including which edits were applied                                     | No             |

### Video replication

| Tool                 | What it does                                                                              | Spends credits |
| -------------------- | ----------------------------------------------------------------------------------------- | -------------- |
| `analyze_video`      | Breaks a TikTok, YouTube Shorts, Reels or direct video link into a shot-by-shot blueprint | Yes            |
| `get_video_analysis` | Reads an analysis and its blueprint                                                       | No             |
| `replicate_video`    | Renders an AI replica from an analysis, with a side-by-side comparison                    | Yes            |
| `get_replication`    | Reads a replication run and its video links                                               | No             |

### Other

| Tool             | What it does                                                                | Spends credits |
| ---------------- | --------------------------------------------------------------------------- | -------------- |
| `wait_for_job`   | Waits on the server for an avatar, short video, analysis or replication job | No             |
| `compare_models` | Renders a side-by-side video of two of your finished generations            | No             |
| `get_compare`    | Reads a `compare_models` render                                             | No             |

## How the tools behave

* **Asynchronous.** Spending tools return an id right away. The assistant then calls `wait_for_generation` or `wait_for_job`, which return when the job ends or after about 45 seconds with `stillRunning: true`.
* **No double charges on retry.** `generate`, `avatar_say`, `analyze_video`, `replicate_video` and `make_video` accept an `idempotencyKey`; a repeat call with the same key returns the original job.
* **Refunds.** Failed generations return their credits, as in the REST API.
* **Errors are JSON with a code.** A failed tool call returns `isError: true` and a body such as `{"code": "INSUFFICIENT_CREDITS", "message": "…", "requiredCredits": 44, "currentCredits": 12, "topUpUrl": "https://app.percify.io/billing"}`. Codes: `INSUFFICIENT_CREDITS`, `MODERATION_REJECTED`, `CONSENT_REQUIRED`, `NAME_TAKEN`, `NOT_FOUND`, `RATE_LIMITED`, `TIMEOUT`, `INVALID_INPUT`, `INTERNAL`.
* **Rate limits.** 60 requests a minute per API key or OAuth token, and 60 generation starts a minute per account. See [Errors and rate limits](/api-reference/errors-and-limits).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Opening the URL in a browser shows a web page, not the server">
    That is expected. A browser visit to `https://mcp.percify.io/mcp` is sent to the setup page on percify.io. MCP clients use `POST` requests, which reach the server.
  </Accordion>

  <Accordion title="The client says 401 Unauthorized">
    For key-based clients, check the header is exactly `Authorization: Bearer pk_live_…` and that the key is not revoked or expired. For Claude, click **Connect** on the connector again to sign in. Every `401` names the sign-in metadata in its `WWW-Authenticate` header, which OAuth clients follow automatically.
  </Accordion>

  <Accordion title="A GET request returns 405">
    The server only answers `POST`. It does not offer a server-sent event stream, so a `405` on `GET` is the expected answer.
  </Accordion>

  <Accordion title="The assistant says there are not enough credits">
    The tool error includes the credits needed and your balance. Top up at [app.percify.io/billing](https://app.percify.io/billing), or ask the assistant to run `estimate_cost` first.
  </Accordion>
</AccordionGroup>

## Disconnect

Remove the Percify connector in your client's connector settings. For clients that use a key, revoke the key on the [developer page](https://app.percify.io/home/developer); it stops working at once.

## For client developers

* OAuth protected resource metadata: [mcp.percify.io/.well-known/oauth-protected-resource](https://mcp.percify.io/.well-known/oauth-protected-resource). The authorization server is `https://api.percify.io`, with dynamic client registration and PKCE `S256`.
* Agent registration guide: [api.percify.io/auth.md](https://api.percify.io/auth.md).
* The server accepts cross-origin requests from any origin and exposes the `WWW-Authenticate` header, so browser-based MCP clients can sign in.

## Related

<CardGroup cols={2}>
  <Card title="API overview" href="/api-reference/introduction">
    The REST API behind the same tools.
  </Card>

  <Card title="Authentication" href="/percify/api-auth">
    Create the pk\_live key for Claude Code, Cursor and Codex.
  </Card>

  <Card title="Talking avatar pipeline" href="/api-reference/avatars/overview">
    What avatar\_say does, step by step.
  </Card>

  <Card title="Credits and usage" href="/api-reference/user/overview">
    Balance, spend and key caps.
  </Card>
</CardGroup>

Setup page on the Percify website: [percify.io/mcp](https://percify.io/mcp).