AI Agents (5am mcp)

5am mcp runs the CLI as a Model Context Protocol server, so an AI agent can use it directly. Your agent gets 87 tools in six toolsets: video editing, your media library, albums, photo edits, Motion films and clip outreach. Every tool runs the CLI's own code, so a frame the agent looks at is the frame the render draws, and a tool does exactly what its command does.

Add It to Your Agent

Install the CLI and sign in once (see the CLI reference), then add the server to your agent. Desktop apps do not read your shell profile, so give them the full path that which 5am prints (here /usr/local/bin/5am).

Claude Code

claude mcp add 5am -- 5am mcp

claude mcp list shows it, and /mcp inside Claude Code shows its tools.

Claude (Desktop App)

1. Open Claude's Settings, then Developer, and click Edit Config. It opens claude_desktop_config.json (on macOS in ~/Library/Application Support/Claude/, on Windows in %APPDATA%\Claude\).

2. Add the server:

   json

   {
     "mcpServers": {
       "5am": {
         "command": "/usr/local/bin/5am",
         "args": ["mcp"]
       }
     }
   }
   

3. Quit Claude completely and open it again. The 5AM tools appear in the tools menu of a new chat.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.5am]
command = "5am"
args = ["mcp"]

Antigravity

Antigravity 2.0, the Antigravity IDE and the Antigravity CLI share one file: ~/.gemini/config/mcp_config.json (on Windows %USERPROFILE%\.gemini\config\mcp_config.json).

1. Open it. In the IDE: the agent panel's ... menu, MCP Servers, Manage MCP Servers, View raw config. Or open the file in any editor.

2. Add the server:

   json

   {
     "mcpServers": {
       "5am": {
         "command": "/usr/local/bin/5am",
         "args": ["mcp"]
       }
     }
   }
   

3. Open Settings, then Customizations, and click Refresh under Installed MCP Servers. In the CLI, /mcp shows it.

Other Clients

Any MCP client that starts a local server over stdio works: run /usr/local/bin/5am mcp, with the flags below when it needs them.

What Else It Needs

• 5am login for the library, the AI tools and the paid exports. The video edit tools work logged out, on files on your machine: every render is then a draft, free and with a small "Powered by 5AM" mark.
• The optional runtime and Node.js 20+ for the photo-edit and Motion tools: 5am update --runtime-only installs it, and 5am motion doctor checks it.
• ffmpeg for video editing and rendering.

Serve Only the Toolsets You Need

claude mcp add 5am -- 5am mcp --tools edit,media

--tools takes any of edit, media, albums, image, motion and outreach (default: all six). Claude Code searches tools as it needs them, so all six are fine there. A client that loads every tool into its context up front works better with only the toolsets the job needs.

Pointing at Node, ffmpeg and Chrome

When your client starts the server without Node or ffmpeg on its PATH, point at them once:

claude mcp add 5am -- 5am mcp --node /opt/homebrew/bin/node --ffmpeg /opt/homebrew/bin/ffmpeg

To act as another account or against another server, start it with a token: 5am --token <personal access token> --base-url <url> mcp. Every tool then uses that account, never your saved login. In a client's env the same goes as 5AM_TOKEN and 5AM_BASE_URL. From CLI v1.8.0 every 5AM_ variable is also read as FIVEAM_ (FIVEAM_TOKEN, FIVEAM_BASE_URL, FIVEAM_CONFIG_DIR, FIVEAM_DISABLE_KEYRING), which is the spelling to use in a shell: a shell cannot export a name that starts with a digit.

Behind a Proxy or in an Agent's Sandbox

Most MCP clients start a server with only a few environment variables (HOME, PATH, USER and the like), so a proxy your terminal uses never reaches it. If the computer reaches the internet through a proxy, as an AI agent's sandbox usually does, pass its settings in the server's env. Run env | grep -i -E 'proxy|ssl_cert' in a terminal there and copy the values it prints:

{
  "mcpServers": {
    "5am": {
      "command": "/usr/local/bin/5am",
      "args": ["mcp"],
      "env": {
        "HTTPS_PROXY": "http://proxy.internal:3128",
        "HTTP_PROXY": "http://proxy.internal:3128",
        "NO_PROXY": "localhost,127.0.0.1",
        "SSL_CERT_FILE": "/etc/ssl/certs/ca-certificates.crt"
      }
    }
  }
}

In Claude Code, add -e NAME=value for each one: claude mcp add 5am -e HTTPS_PROXY=http://proxy.internal:3128 -- 5am mcp. In Codex, put them in an env = { ... } table under [mcp_servers.5am]. SSL_CERT_FILE matters when the proxy inspects traffic with its own certificate.

What Your Agent Can Do

Every toolset also comes with credits (your balance), credits_buy and credits_wait (see Credits), files_list (what is in a folder, with durations and sizes) and cli_help (every flag of any tool).

What It Asks You First

The tools are built so an agent cannot spend your money, email anyone or delete things behind your back:

• Paid steps wait for your yes. A Motion export (20 AI credits) and the outreach clips (20 credits each) start with a free dry run. The agent tells you the price and asks; without your yes the command refuses ("not confirmed; pass --yes").
• Video exports come once, at the end. From CLI v1.8.0, the agent iterates on drafts (draft: true: free, with a small "Powered by 5AM" mark), prices the final cut with a dry run (dry_run: true, nothing charged), and exports it without the mark after you agree: 50 AI credits at the current price, which may change, never twice for the same file. If the fee is refused, the render is kept for 24 hours and edit_finalize pays for it and delivers it without rendering again.
• Credits are bought only by a person. The agent makes a payment link or asks the account owner only when you want it to; nothing is charged until someone pays or approves, and an agent's token can never approve. See Credits.
• Email waits for your yes too. outreach_send sends only drafts you approved, from your own Gmail, and only after you confirm the send.
• Deletes are marked destructive. Your client shows you a delete or unshare before it runs, and that approval is the confirmation.
• The review is yours. Approving an outreach draft is your step, in your AI character's chat. The agent never publishes a prospect's clip page.
• Some steps stay with you on purpose. Setting up your Gmail app password (5am outreach mail setup) happens in your terminal, so the password never passes through an agent. The live preview and the review page wait for a person, so they are not tools.
• Video editing stays on your machine. The edit tools read and render your files with your ffmpeg; your video never uploads. An export only tells 5AM the finished file's fingerprint to charge its fee.

Each tool's description says what it costs and what it touches, so your agent can tell you before it acts.

Examples

Ask in plain words. The agent picks the tools; here is what each request turns into.

Cut a Highlight From an Interview

Make a 60-second vertical highlight of interview.mp4 with bold captions. Check it before you render.

1. media_transcribe transcribes the talk (AI credits, or your Gemini key) and saves interview.transcript.json beside it.

2. edit_transcript reads the segments, and the agent drafts a script:

   vedl

   source "interview.mp4"
   cut 01:00 01:20
   text "Meet the founder" at 0 for 3
   

3. edit_check returns any errors, the timeline and a contact sheet of the key frames, which the agent looks at.

4. edit_change fixes what it saw, line by line, and saves the script:

   json

   {
     "path": "highlight.vedl",
     "save": true,
     "changes": [
       { "action": "times", "line": 2, "start": "1:04", "end": "1:20" },
       { "action": "add", "after": 3, "text": "captions style=bold accent=#ffee00" }
     ]
   }
   

5. edit_render writes a draft and measures it in the same call (frame rate, loudness, true peak, text inside the safe area). The agent repeats steps 3 to 5 until it looks right:

   json

   { "path": "highlight.vedl", "output": "highlight.mp4", "aspect": "9:16", "draft": true }
   

6. For the final cut, edit_render with dry_run: true prices the export, the agent asks you, and the same call without draft exports it (50 AI credits, from CLI v1.8.0).

Long renders report progress, and cancelling the call stops the render. Before CLI v1.8.0 every render is free and carries the free-tier watermark when you are not signed in.

To adjust it yourself instead, ask the agent to open it in the web editor: edit_export (from CLI v1.8.0) uploads the media to an album, makes a Video Editor project of the edit and returns a url that opens it. The cuts, transitions, titles, overlays and the compatible grade are ordinary editor items there:

{ "path": "highlight.vedl", "new_album": "Interview reel" }

It is free; the media counts toward your storage. The web editor does not yet reproduce ducking, fades or some grading, so keep the agent's export when exact playback matters.

Retouch Product Photos

Make these 12 product shots in ./shots brighter, square and on white, then upload them to a new album called Spring catalog.

1. image_edit_generate writes an IEDL recipe from your description.
2. image_edit_render renders one photo and shows it to the agent, which adjusts the recipe until it looks right.
3. image_edit_batch runs the recipe over the folder, on your machine.
4. media_upload uploads the results with new_album: "Spring catalog".

Local recipes are free. Selecting, erasing and generative edits run on library photos and cost AI credits; the tool says so first.

Make a Motion Film

Make a 15-second 9:16 launch film for our app, using the photos in my Launch album.

1. motion_generate writes the film from your brief.
2. motion_lint checks it, and motion_stills or motion_sheet shows frames, both free.
3. motion_revise changes it in plain language ("slower opening, bigger headline").
4. motion_render runs a free dry run first, tells you it costs 20 AI credits, and exports once you say yes.

Or start from the motion_film prompt with your brief, format and duration.

Run an Outreach Batch

Use the outreach_batch prompt with your prospects CSV, a Motion template and a batch name. The agent:

1. prepares one film per prospect (outreach_prepare, free);
2. prices the clips with a dry run and waits for your yes (outreach_clips, 20 credits each);
3. renders them and stages the drafts (outreach_draft), which posts a review card in your AI character's chat;
4. stops.

You review and approve the drafts in the chat, on the web or in the apps. Then ask it to send: outreach_send does a dry run, asks you, and sends only what you approved, from your Gmail.

Find and Share Photos

Find my photos of the beach from last summer, put them in an album and share it with ana@example.com.

media_semantic_search finds them by meaning, albums_create and media_upload (or the library ids) build the album, and albums_share invites Ana. Every share call emails each person named again, so the agent shares once.

Guides and Prompts

Each toolset brings guides your agent reads before it works, so it writes valid scripts, recipes and films the first time:

Prompts start a task with the right steps: vedl_edit (goal, source), image_edit (goal, image), motion_film (brief, format, duration) and outreach_batch (csv, template, batch).

Tool Arguments

A tool's arguments are its command's flags with underscores (added_after for --added-after) and its positional arguments by name. The flags a first call needs are typed; the rest go in options:

{ "batch": "oct_week_1", "dry_run": true, "options": { "gif_seconds": 4, "no_gif": true } }

cli_help (or the cli://help/{name} resource) lists every flag a tool takes, where it goes and its default. An unknown name is refused, never silently dropped.

Credits

Tools that spend AI credits say so in their descriptions. When the balance runs out, the tool fails with a credits message (category credits), and the agent tells you. It buys nothing on its own: credits_buy runs only when you ask for credits.

• credits shows your balance and the packs on sale (5,000 credits for $6.99, 20,000 for $24.99, 50,000 for $59.99; purchased credits never expire).
• credits_buy gets you a pack one of three ways:
  • A payment link (the default): returned at once with its id and url. The link pays on any device without signing in, and nothing is charged until someone pays. It lasts 30 minutes. From CLI v1.8.0, reason shows on the page (what the credits are for and how many are needed), and options.valid_for keeps the link up to 24 hours for a person who reads the message later.
  • A Link token (options.spt, from CLI v1.8.0): when you use Link's wallet for agents, you approve a spend request in the Link app and the agent pays with the one-time token Link gives it. credits prints the exact steps in agent_payments.how. It takes no reason.
  • Asking the owner (options.ask_owner, from CLI v1.8.0): for an agent nobody is watching. The request arrives as a card in the account owner's 5AM Comms chat, with a push to their phone, and they approve and pay, or decline, on the web or in the apps. Every plan can answer it. Asking again returns the same request.
• credits_wait waits until the purchase lands, so the agent can carry on. From CLI v1.8.0, link follows a payment link, options.payment a Link token payment and options.request a request to the owner; earlier versions wait for the balance to grow (options.since, the purchased_total_micros that credits_buy printed). It ends on added (with the new balance), review (paid, and being checked; the credits follow), or rejected, refunded, disputed, declined or expired (no credits). not_received means the wait timed out first: call it again.

Troubleshooting

• "Skia isn't installed": run 5am update --runtime-only. Photo edits and Motion render with Skia; 5am motion doctor checks it.
• The photo-edit or Motion tools cannot find Node, or the edit tools cannot find ffmpeg: your client did not read your shell profile. Add --node or --ffmpeg with full paths (see Pointing at Node, ffmpeg and Chrome).
• A library or AI tool says you are not signed in: run 5am login in a terminal, then restart the server in your client.
• Every library or AI tool fails with a TLS or certificate error, but the same command works in a terminal: the computer reaches the internet through a proxy and your client did not pass its settings to the server. Add them to the server's env (see Behind a Proxy or in an Agent's Sandbox), then restart the server.
• "not confirmed; pass --yes": expected. A paid step or a send is waiting for your yes; tell the agent to go ahead.
• An export rendered but its fee was refused (no credits left, or a network error): the file is kept for 24 hours. Buy credits, then ask the agent to run edit_finalize; it delivers the kept render without rendering again.
• Too many tools for your client: serve fewer with --tools.

The server speaks MCP over stdio (protocol versions 2025-06-18, 2025-03-26 and 2024-11-05), with tools, resources, prompts, progress and cancellation.