FOTOhub MCP server: use FOTOhub from your AI assistant

Developers and integrations · Intermediate · 14 min read · Updated

Connect FOTOhub to an AI assistant or editor over MCP with an API key or a sign-in, see the 73 tools it exposes, and keep spending under control.

The MCP page on fotohub.app: a live handshake sketch and the transport, protocol and auth summary.

What MCP gives you

The Model Context Protocol (MCP) is an open standard that lets an AI assistant call tools on another service. FOTOhub runs an MCP server, so an assistant that speaks MCP can generate and edit images, make video and speech, transcribe audio, build 3D models, price a job, read your balance and save results to your storage, all by calling FOTOhub tools you never wrote code for.

Value
Endpointhttps://apis.fotohub.app/mcp/
Dedicated hosthttps://mcp.fotohub.app/
TransportStreamable HTTP (remote, no install)
ProtocolMCP 2025-03-26
Sign-inA bearer API key, or OAuth 2.1 with PKCE and dynamic client registration
Live healthGET https://apis.fotohub.app/mcp/health reports the current tool count
The MCP page on fotohub.app: a live handshake sketch and the transport, protocol and auth summary.
The MCP page on fotohub.app: the handshake, the surface and ready-made connection snippets. Its tool counts lag the live server, so trust the health endpoint.

Connect a client

Pick one of two ways to prove who you are. Most clients that have a connector screen use the sign-in; editors and scripts use a key.

Sign-in (OAuth)API key
HowThe client opens a FOTOhub sign-in page and you approve it. No key to paste.You paste fh_live_... into a header.
What paysSubscription credits first, then the prepaid USD wallet. One call can be split across both.The USD wallet only.
Best forAssistants with a connectors screenEditors, CLIs, scripts, servers

An assistant with a connectors screen

  1. Add a custom connector In the assistant's settings, open Connectors (or Apps), choose to add a custom connector, and paste the endpoint URL. For ChatGPT, if FOTOhub appears in your app directory you can enable it there instead of pasting a URL.
  2. Approve the sign-in The assistant finds FOTOhub's authorization server by itself and opens a sign-in page. Approve it with your FOTOhub account. The client registers itself, so nobody has to create a client id for you.
  3. Try a free request first Ask: "What is my FOTOhub balance, and what would a 4-second video cost?" Reading a balance and quoting a price take nothing from your account.

Command line and code editors

Editors and agents that read an MCP config file take the URL plus an Authorization header. This shape works for Cursor (.cursor/mcp.json), and similar clients accept it with small naming differences:

{
  "mcpServers": {
    "fotohub": {
      "type": "http",
      "url": "https://apis.fotohub.app/mcp/",
      "headers": { "Authorization": "Bearer fh_live_your_key_here" }
    }
  }
}

A command-line agent registers a remote server with one command, then you authenticate inside it:

claude mcp add --transport http fotohub https://apis.fotohub.app/mcp/

FOTOhub's own command-line client can set this up with your existing key: run fotohub mcp connect. It can also act as a local stdio MCP server for editors that only speak stdio: fotohub mcp serve.

Connection snippets on the MCP page for the remote and the local transport.
Connection snippets on the MCP page for the remote and the local transport.

How the sign-in works

The client does all of this for you. It helps to know the steps when a connector refuses to finish, or when you build your own client. Every address below is public and opens without a key.

  1. A 401 with a pointer A request without a token gets HTTP 401 and a WWW-Authenticate header naming https://apis.fotohub.app/mcp/.well-known/oauth-protected-resource. That starts the sign-in.
  2. Discovery and registration https://apis.fotohub.app/.well-known/oauth-authorization-server lists /mcp/oauth/authorize, /mcp/oauth/token and /mcp/oauth/register, the authorization_code and refresh_token grants and S256 as the only PKCE method. A POST to /mcp/oauth/register creates the client id on the spot; only redirect addresses given there are accepted later.
  3. You sign in and approve The client opens /mcp/oauth/authorize with a PKCE challenge, the scopes it wants and the resource it will call. FOTOhub shows "Authorize access", asks you to sign in and lists each scope in plain words. Choose Authorize access or Cancel. With no scope requested, mcp:read mcp:write is assumed.
  4. Code for tokens The one-time code lives 10 minutes. The client posts it to /mcp/oauth/token with the PKCE verifier and gets an access token valid for one hour and a refresh token valid for 90 days. Each refresh retires the old refresh token and issues a new pair.
ScopeWhat the consent screen says
mcp:readRead your account: models, jobs, files, wallet balance
mcp:writeCreate and manage content: start generations, manage your library
mcp:imageGenerate and edit images, charged per image
mcp:videoGenerate and post-produce video, charged per second of output
mcp:audioGenerate speech and music, charged per character or minute
mcp:chatSend prompts to the language gateway, charged per token
mcp:trainingTrain custom models, long-running, billed per job
mcp:billingSee balance and spending, read-only, cannot move money

The 73 tools

A client discovers the tools itself with tools/list, so nothing is hard-coded on its side. At the time of writing the live server exposes 73 (the health endpoint reports the same number). 24 of them only read and carry a read-only hint; the rest create or change something, including anything that spends money, and should be approved by you.

The tool surface section of the MCP page, grouped by area, with the resources and prompt templates below.
The tool surface on the MCP page, grouped by area. The tables below are built from the live tools/list answer.

An asterisk marks a required argument; everything else has a default.

Images

ToolWhat it doesMain argumentsRead-only
generate_imageText to imageprompt*no
edit_imageEdit by mode (edit, inpaint, outpaint, style, background)image_url*, prompt*no
inpaint_imageReplace a masked areaimage_url*, mask_url*, prompt*no
style_transferApply a described styleimage_url*, style_prompt*no
upscale_imageEnlarge 2x or 4ximage_url*no
remove_backgroundTransparent PNG cut-outimage_url*no
enhance_promptEnrich a promptprompt*no
analyze_imageLabels, colors, faces, textimage_url*no

Image finishing

ToolWhat it doesMain argumentsRead-only
replace_backgroundNew backdrop: hex color, gradient or image URLimage_url*, background*no
blur_backgroundPortrait-style blurimage_url*no
add_shadowShadow under a transparent cut-outimage_url*, shadow_typeno
enhance_imageExposure, contrast and color fiximage_url*no
denoise_imageRemove grainimage_url*no
restore_facesSharpen degraded facesimage_url*no
depth_mapDepth map from one imageimage_url*no

Video and post-production

ToolWhat it doesMain argumentsRead-only
generate_videoText or image to video. Async, returns a job idprompt*, modelno
image_to_videoAnimate a still. Asyncimage_url*no
generate_storyMulti-scene film; waits to the end, no job idprompt*, num_scenesno
get_job_statusStatus of generate_video and image_to_video jobsjob_id*yes
add_subtitlesBurn in an SRT you supply; no transcriptionvideo_url*, srt_content*no
upscale_videoRaise resolution 2x to 4xvideo_url*no
transcode_videoChange format, codec or sizevideo_url*no
add_watermarkText watermark onlyvideo_url*no
change_video_speedSlow motion or time-lapse, 0.1 to 10video_url*, speed*no

Video editor (timeline projects)

These tools edit the same timeline project the FOTOhub editor opens, so you can take over in the browser at any point. Edit tools count time in ticks (6000 per second); analysis tools use seconds.

ToolWhat it doesMain argumentsRead-only
video_project_createNew project from media URLs; freetitle*, mediano
video_project_getRead or list projectsproject_idyes
video_ops_catalogEvery edit operation with its schemanoneyes
video_apply_edit1 to 40 operations per batch; freeproject_id*, ops*no
video_lintGaps, overlaps, missing mediaproject_id*yes
video_captureContact sheets of frames. Asyncproject_id*, timesno
video_renderFinal file, paid per output minute. Asyncproject_id*, qualityno
video_job_statusStatus of editor render, capture and auto-edit jobsjob_id*yes
video_auto_editEditor AI cuts in a style; one base fee. Asyncproject_id*, styleno
video_detect_scenesScene cuts in secondsurl, project_idno
video_detect_silenceSilent stretchesurl, project_idno
video_detect_beatsBeats of a trackurl, project_idno
video_transcribeSegments and word times in secondsurl, project_idno

Audio and language

ToolWhat it doesMain argumentsRead-only
text_to_speechSpeech from texttext*, voiceno
generate_musicMusic from a description; synchronousprompt*, durationno
generate_sfxSound effect from a descriptionprompt*, durationno
transcribe_audioSpeech to text with timestampsaudio_url*, languageno
voice_clonePlaceholder, not available yetaudio_url*, name*no
separate_stemsPlaceholder, not available yetaudio_url*no
chat_completionPrompt to a premium language modelprompt*, modelno
translate_textTranslate between languagestext*, target_languageno
gabriel_routeSuggests the best action for a requestprompt*no

3D

ToolWhat it doesMain argumentsRead-only
generate_3d_from_textModel from a descriptionprompt*, qualityno
generate_3d_from_imageModel from one image, as base64 without data: prefiximage_base64*, modelno
list_3d_models3D models with pricesnoneyes
get_3d_resultFinished model, fresh linkjob_id*yes

Pricing and account (all free)

ToolWhat it doesMain argumentsRead-only
get_priceExact price of one modelmodel*yes
estimate_costCost of a job before you run itmodel*, countyes
compare_pricesA whole category side by sidecategory*yes
check_balanceWallet, holds, spend this monthnoneyes
list_modelsModels with pricingcategoryyes
list_generationsLatest images, at most 12limityes
get_usage_summaryLast 30 days of usagenoneyes
get_transactionsRecent wallet transactionslimityes
search_photosSemantic search in your photosquery*yes

Storage

ToolWhat it doesMain argumentsRead-only
list_bucketsYour buckets (bought in the console)noneyes
list_filesFiles in a bucketbucket*, prefixyes
save_to_storageCopy a file into a bucket; replaces an object at that keyurl*, bucket*, key*no
get_download_linkFresh signed link, 7 days at mostbucket*, key*yes

UGC ads

ToolWhat it doesMain argumentsRead-only
create_ugc_projectStart a project; freetitle, briefno
list_ugc_projectsYour projectsnoneyes
set_ugc_blueprintSave the shooting document; overwritesproject_id*, blueprint_json*no
estimate_ugc_costPrice a blueprintdocument*yes
render_ugc_videoStart the render; scenes billed as they finishproject_id*no
get_ugc_jobProgress and cost so farjob_id*yes

Integrations

ToolWhat it doesMain argumentsRead-only
integrations_listConnections and their actionsnoneyes
integration_run_actionRun one action on a connectionconnection_id*, action*no
automations_listYour automationsnoneyes
automation_runRun one nowautomation_id*, payloadno

How slow work behaves

  • Image and speech tools return signed links that expire after roughly an hour. Have the assistant save_to_storage anything you keep; get_download_link issues a fresh link later.
  • Video is asynchronous: the tool returns a job id and the assistant polls get_job_status. Editor jobs (video_render, video_capture, video_auto_edit) are polled with video_job_status instead; get_job_status does not know them.
  • generate_story is the exception: it returns only when the whole film is done and hands back no job id, so a dropped connection loses the result. Tool calls time out after fifteen minutes by default.

Resources, prompts, widgets and skills

  • Resources the model can read: fotohub://models/image, /video, /audio, /3d, fotohub://pricing, fotohub://balance, fotohub://limits and fotohub://guide/getting-started.
  • Prompts your client can offer as templates with named fields: creative_brief, video_director, product_photo, ecommerce_product_shots, social_media_pack, ugc_ad_pipeline (asks for product_name, target_audience, budget_usd), avatar_profile_photo, voiceover_script and budget_constrained_generation.
  • Widgets: a gallery (image tools), a player (video and audio tools) and a price table that hosts supporting the MCP Apps extension draw inline. Other clients show the plain text that always accompanies them.
  • Skills: short workflow guides served with the tools: generation basics, product photography, a short video ad, a brand-kit set and, when the editor tools are on, video editing.

A session you can run

Behind every assistant is plain JSON-RPC. This script opens a session with a key, lists the tools and calls one free tool, which shows exactly what your assistant sees. It needs only httpx.

import json
import os

import httpx

URL = "https://apis.fotohub.app/mcp/"
HEADERS = {
    "Authorization": f"Bearer {os.environ['FOTOHUB_API_KEY']}",
    "Accept": "application/json, text/event-stream",
    "Content-Type": "application/json",
}


def rpc(client, payload, session=None):
    """One JSON-RPC call. The server answers as a one-event SSE stream."""
    headers = {**HEADERS, **({"Mcp-Session-Id": session} if session else {})}
    res = client.post(URL, json=payload, headers=headers, timeout=60)
    res.raise_for_status()
    data = next((line[6:] for line in res.text.splitlines() if line.startswith("data: ")), None)
    return res.headers.get("mcp-session-id"), (json.loads(data) if data else None)


with httpx.Client() as client:
    # 1. Open a session.
    session, init = rpc(client, {
        "jsonrpc": "2.0", "id": 1, "method": "initialize",
        "params": {"protocolVersion": "2025-03-26", "capabilities": {},
                   "clientInfo": {"name": "docs-demo", "version": "1"}},
    })
    print(init["result"]["serverInfo"])
    rpc(client, {"jsonrpc": "2.0", "method": "notifications/initialized"}, session)

    # 2. Ask what exists.
    _, listing = rpc(client, {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, session)
    print(len(listing["result"]["tools"]), "tools")

    # 3. Call a free tool.
    _, call = rpc(client, {
        "jsonrpc": "2.0", "id": 3, "method": "tools/call",
        "params": {"name": "get_price", "arguments": {"model": "ida-q-image"}},
    }, session)
    print(call["result"]["content"][0]["text"])
  • Send Accept: application/json, text/event-stream. The server answers every request as a one-event stream, so read the line that starts with data: .
  • The initialize answer carries an Mcp-Session-Id header. Send it back on every later call.
[output] $0.13 / per_piece  (by quality tier: 1K=$0.13, FULL=$0.61, HD=$0.29)
    per delivered image, balanced preset; FOTOhub AI own GPU, no provider invoice

The price lines of a real get_price call for ida-q-image (the first line, the model name, is left out). An example of one call, not a price promise.

Tools that return a structured answer carry it next to the text. This is the trimmed structured part of a real check_balance call:

{
  "title": "FOTOhub balance",
  "balance_usd": 80.782028,
  "total_label": "wallet balance",
  "rows": [
    { "label": "Pending holds", "usd": 0.0 },
    { "label": "Spent this month", "usd": 40.768547 }
  ],
  "footnote": "Top up at fotohub.app/console. Checking a balance is free."
}

Example from a real call, trimmed. actions (suggested follow-up prompts) is left out.

Five workflows to give your assistant

Each example shows the prompt you give and the calls it should trigger, so you can tell when an assistant goes off script. Swap the example URLs for your own files.

Product cut-out, backdrop and shadow

Goal. Turn a phone photo into a white-background listing image and keep it.

Input you can copy.

"Cut the shoe out of https://example.com/shoe.jpg, put it on pure white with a natural shadow, and save it to my bucket listings as shoe/white.jpg. Quote each step first."

Why it works. Expected calls: get_price per step, then remove_background, which returns a transparent PNG link (a good assistant checks the edges). Then add_shadow with that link, shadow_type "natural" and output_format "jpeg": the shadow tool needs a transparent PNG as input, and a JPEG output is matted onto white, so you get the white backdrop in the same step. list_buckets confirms the name, then save_to_storage with the exact link the last tool returned, at once, because those links last about an hour. For a coloured or photo backdrop use replace_background with a hex color, gradient or image URL.

Price a video before rendering it

Goal. Know the price of a short vertical clip and stop for your approval first.

Input you can copy.

"I want a 5-second vertical video of steam rising from a coffee cup. Compare video model prices, estimate the three cheapest, check my balance and wait for my OK."

Why it works. Expected calls, all free: compare_prices with category "video", estimate_cost per candidate (with seconds, and a resolution for models priced by resolution), check_balance. If a model prices by tier, estimate_cost answers with the argument it still needs instead of a number; for ida-q-image it asked for quality and listed the tiers 1K, FULL and HD. After your OK: generate_video with aspect_ratio "9:16" and duration 5, then get_job_status until it reports completed, then save_to_storage.

Transcribe and translate

Goal. Get the words of a recording with timestamps, then an English version.

Input you can copy.

"Transcribe https://example.com/interview.mp4, the speech is Polish, then translate the transcript into English. Quote the price first."

Why it works. Expected calls: estimate_cost with minutes, transcribe_audio with audio_url and language "pl" ("auto" detects it; video files work too), then translate_text with target_language "en" and source_language "pl". For word-level timings to cut on, ask for video_transcribe: it returns segments and words in seconds, takes hotwords to favour names, and marks interpolated words as estimated, so do not cut on those. If a long file is still running, the assistant repeats the call with the job_id from the reply.

Keep results in your own bucket

Goal. Move the picture you just generated out of the one-hour link window.

Input you can copy.

"Save my latest generated image into brand-assets as campaign/hero.png, confirm it is there and give me a link that works for 24 hours."

Why it works. Expected calls: list_buckets, list_generations with limit 1 (each row has a fresh link), save_to_storage with that link, list_files with prefix "campaign/", then get_download_link with expires_in 86400. Only save_to_storage writes, and it replaces any object already at that key, which is why it is marked destructive and your client should ask first. The bucket must already exist; buckets are bought in the console. list_generations covers images only.

Run an integration action

Goal. Post a result to a service you already connected.

Input you can copy.

"Which integrations do I have connected? Send the shoe cut-out (photo id 3f2c...) to my team chat channel #launch."

Why it works. Expected calls: integrations_list first; it returns each connection's id, service, status and actions, and is the only place the assistant should take connection_id and action names from. Then integration_run_action with params.media set to {"type": "photo", "id": "<photo uuid>"}. Using {"type": "generate", "prompt": "..."} instead would generate something new, billed to you. The tool is marked destructive because it acts on an outside service, so approve it each time. For a saved workflow use automations_list and automation_run.

The editing loop for video projects

  1. Create and read the catalog video_project_create with HTTPS media URLs (free; you get an editor link), then video_ops_catalog for the exact fields of every operation.
  2. Edit, check, repeat video_apply_edit takes up to 40 operations; try a batch with dry_run. Then video_lint and video_capture. Do not render to check an edit.
  3. Render once video_render is paid per minute of output. Poll video_job_status and pass an idempotency_key so a retry cannot render twice.

Money and safety

Sign-in (OAuth) connectionKey you paste
Pays firstSubscription credits, then the USD wallet, even inside one callThe prepaid USD wallet only; empty means the call stops
Cost lineCredits used, or credits plus a cost when the wallet covered the restCost and what is left in the wallet
  • Quote first. get_price, estimate_cost and compare_prices never charge, and they read the live catalog, so they beat the assistant's memory. Tell it to quote before anything expensive. The same numbers sit in fotohub://pricing.
  • Read the cost line. Generation tools end with one of three lines: included in your plan with nothing charged, credits used with what is left, or a dollar cost with the wallet that remains. Ask the assistant to repeat it, not to compute its own.
  • Read the hints. Every tool declares readOnlyHint, destructiveHint and openWorldHint. The 24 read-only tools change nothing, so auto-approving them is low risk. Anything that spends money is not read-only, even when it returns only text. Four tools are destructive and deserve a manual yes: save_to_storage (replaces an object), set_ugc_blueprint (overwrites a blueprint), integration_run_action and automation_run (act on outside services).
  • Limit the blast radius. A key's rate limit and scopes apply to MCP calls too. Tools that fetch a URL (image_url, video_url, audio_url, url) are marked open-world: the server downloads that address, so keep untrusted pages out of the conversation. MCP calls show up in the console Request Log like any other.
The Request Log filtered to one model, with the Live toggle and CSV export.
The console Request Log, where calls made through an assistant sit next to the rest of your traffic.

Limits and production checklist

WhatLimit
One tool call15 minutes by default
Result linksAbout one hour
get_download_link1 hour by default, 7 days at most
video_apply_edit1 to 40 operations per batch
OAuth tokensAccess 1 hour, refresh 90 days, code 10 minutes
  • Keep approval on for every tool that is not read-only. Add "quote first, then wait for my OK" to the assistant's standing instructions for video, 3D or many images.
  • Save what you keep right after it is made, with a key name you choose, so a later run does not replace it. Pass an idempotency_key on renders you might retry.
  • Check GET https://apis.fotohub.app/mcp/health and the Request Log before you blame the assistant.

Troubleshooting

The connector is added but shows no tools.
Authentication did not finish. Remove the connector, add it again and complete the sign-in. With a key, check that the header is Authorization: Bearer fh_live_... and the key is active.
I get 401 on every call.
The sign-in token or the key was revoked or is wrong. A key must start with fh_live_ or fh_test_; anything else is rejected as a bad format. Revoking the "MCP OAuth" key in your key list ends that connection. Sign in again or create a new key.
The sign-in page fails or says the redirect is not registered.
Only redirect addresses given at registration are accepted. Remove the connector and add it again so the client registers afresh. If the page says you have too many active keys, revoke one in the console first.
A tool answers "insufficient funds".
Credits (for sign-in connections) and the wallet are both empty. Top up under Billing & wallet in the console. A key connection has only the wallet.
save_to_storage says the link has expired.
Result links last about an hour. For an image, list_generations returns fresh links to your latest ones. For video or audio, generate again, which is why saving right away matters.
Can FOTOhub also use other MCP servers?
Yes, the other direction exists too: the integrations hub has an MCP and AI tab where you add an external MCP server, approve its tools and use them in automations.
The MCP and AI tab: your MCP servers, tool approvals and test call.
The other direction: the MCP and AI tab of the integrations hub, where external MCP servers are added and their tools approved.

Next, read integrations for connecting the services these tools act on, api-keys for a restricted key, api-errors-limits for the status codes behind a failed call (401, 402, 403, 404, 429), and s3-storage for the buckets save_to_storage writes to.

Open the MCP page

Open FOTOhub MCP server in FOTOhub