Percify MCP server for Claude, ChatGPT, Cursor and Codex

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

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

Which plan you need depends on how your client signs in. Connecting over OAuth works on every plan, including the free one: you sign in to Percify in the browser, click Authorize, and the assistant spends credits from your balance like the app does. A client that cannot open a browser needs an API key instead, and keys are created on the developer page on the Scale and Ultra plans. Credits themselves are pay as you go: a one-time pack needs no subscription and never expires. See Authentication.

What it costs to start

Three facts, because they are usually assumed to be one:

	What it needs
MCP over OAuth	Every plan, including free. Sign in through the browser, click Authorize, done.
API keys (`pk_live_…`)	Scale or Ultra, for clients that cannot open a browser
Credits to run anything	A plan, or a one-time credit pack with no subscription at all

So an agent can be talking to Percify on a free account in two clicks, with no card and no subscription. Credits are pay as you go: packs start at 200 credits for $5, need no plan, and never expire — buy them when you need them and they sit on the account until you spend them. A subscription only changes how many credits arrive each month; it is not what unlocks the server.

Add Percify to your client

Claude
ChatGPT
Claude Code
Cursor
Codex CLI

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Batches

Tool	What it does	Spends credits
`batch_generate`	Runs one model over up to 50 prompts as a server-side batch, so the client can hang up	Yes
`get_batch`	Polls a batch. Counts are read back from the generations, so an interrupted batch still reports the truth, and polling resumes the prompts it had not reached	No
`list_batches`	Recent batches with status, model, persona and credits spent	No
`stop_batch`	Stops new prompts being submitted. Anything already generating finishes and is still charged	No

A batch takes a budgetCredits ceiling, enforced before each submission rather than reported afterwards. The same thing over REST is POST /v1/batches.

Avatar persona images

Tool	What it does	Spends credits
`add_persona_images`	Adds reference images to a saved persona, up to 12 in total including its frame	No
`edit_persona_images`	Removes reference images from a persona, or chooses which one leads the set	No

Speaking avatars

Tool	What it does	Spends credits
`list_say_models`	Which models can run each half of `avatar_say`, voice cloning and lip-sync	No
`estimate_say`	Prices an `avatar_say` before running it, for the chosen models	No

Composer rounds and Library

The same rounds the app’s Plays tab deals: three cards, face down. Actions taken here are logged as an agent’s, not a person’s.

Tool	What it does	Spends credits
`todays_round`	A brand’s plays for today, dealt in rounds of a few cards	No
`reveal_round`	Turn one of today’s rounds over. It then counts as shown	No
`shuffle_round`	Reroll every card in a round that is not approved. Approved cards never move	No
`approve_play`	Approve a play, as the Approve button does. It goes on the brand’s Library shelf	No
`undo_approve`	Take back an approval made here or in the app	No
`pass_play`	Pass on one card. It is voted down, so that kind comes round less for this brand	No
`save_to_library`	Save a play to the shelf now, without rendering it	No
`list_library`	The brand’s Library shelf: saved, approved and scheduled, newest first	No
`remove_from_library`	Take a play off the shelf. Its approval goes too	No
`download_library`	A video file for each play on the shelf, newest first	No

The same loop over REST is the Composer API.

Brand OS

Reading a brand, writing its words into a proven short video format, rendering it and publishing it. Requires a brand on the account.

Tool	What it does	Spends credits
`read_brand`	Reads a brand from its website. Returns a brandId at once	Yes
`list_brands`	The account’s brands with id, name, domain and status	No
`get_brand`	One brand in full: status, logos, palette, fonts, socials and its DNA	No
`list_plays`	The play library. A play is a short video format taken from a post that performed	No
`write_take`	Writes a brand’s words into a play, the text for each slot from one angle	No
`render_play`	Renders a brand’s version of a play to an MP4 from its current take	Yes
`get_render`	A `render_play` job: running, done with a videoUrl, or failed	No
`get_autopilot`	A brand’s autopilot: on or off, whether it can post and why not, platforms and time zone	No
`set_autopilot`	Turns a brand’s autopilot on or off, or changes when and where it posts	No
`run_autopilot`	Fills a brand’s empty autopilot slots now instead of at the next pass	Yes
`get_brand_performance`	What performs for a brand, from its own published posts	No
`list_social_accounts`	The social accounts connected to this Percify account	No
`schedule_post`	Publishes, schedules or drafts a post on connected accounts. Publishing makes it public	No
`get_post`	A post made with `schedule_post` and its status	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.

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.

Get started

Generations

Jobs and webhooks

Product endpoints

Composer and MCP

Percify MCP server for Claude, ChatGPT, Cursor and Codex

Server details

What it costs to start

Add Percify to your client

What tools does the Percify MCP server have?

Models and generations

Avatar personas

Short videos

Video replication

Batches

Avatar persona images

Speaking avatars

Composer rounds and Library

Brand OS

Other

How the tools behave

Troubleshooting

Disconnect

For client developers

API overview

Authentication

Talking avatar pipeline

Credits and usage

​Server details

​Which sign-in should I use?

​What it costs to start

​Add Percify to your client

​What tools does the Percify MCP server have?

​Models and generations

​Avatar personas

​Short videos

​Video replication

​Batches

​Avatar persona images

​Speaking avatars

​Composer rounds and Library

​Brand OS

​Other

​How the tools behave

​Troubleshooting

​Disconnect

​For client developers

​Related

API overview

Authentication

Talking avatar pipeline

Credits and usage

Server details

Which sign-in should I use?

What it costs to start

Add Percify to your client

What tools does the Percify MCP server have?

Models and generations

Avatar personas

Short videos

Video replication

Batches

Avatar persona images

Speaking avatars

Composer rounds and Library

Brand OS

Other

How the tools behave

Troubleshooting

Disconnect

For client developers

Related