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

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 and need a Scale or Ultra plan. See Authentication.

Add Percify to your client

Claude

These steps follow Claude’s custom connector guide for individual Free, Pro and Max plans. Free plans can add one custom connector.

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

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

3. 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?”

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

ChatGPT

OpenAI’s developer mode guide says developer mode is available on ChatGPT Pro, Plus, Business, Enterprise and Education accounts on the web, supports streaming HTTP MCP servers and OAuth.

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

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

3. Sign in to Percify

   When ChatGPT opens the Percify sign-in, log in and click Authorize.

ChatGPT’s menus change often; if a label differs, follow OpenAI’s current guide.

Claude Code

Run this with your API key in PERCIFY_API_TOKEN:

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.

Cursor

Add the server to ~/.cursor/mcp.json for all projects, or .cursor/mcp.json in one project:

{
  "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.

Codex CLI

Add this to ~/.codex/config.toml. Codex reads the key from the environment variable you name:

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

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.

Troubleshooting

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.

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.

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.

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, or ask the assistant to run estimate_cost first.

Disconnect

Remove the Percify connector in your client’s connector settings. For clients that use a key, revoke the key on the developer page; it stops working at once.

For client developers

• OAuth protected resource metadata: 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.
• The server accepts cross-origin requests from any origin and exposes the WWW-Authenticate header, so browser-based MCP clients can sign in.

Related

API overview

The REST API behind the same tools.

Authentication

Create the pk_live key for Claude Code, Cursor and Codex.

Talking avatar pipeline

What avatar_say does, step by step.

Credits and usage

Balance, spend and key caps.

Setup page on the Percify website: percify.io/mcp.