frameio-mcp

A remote Model Context Protocol server running on Cloudflare Workers that exposes the Adobe Frame.io V4 API as MCP tools, using Frame.io's official TypeScript SDK.

Authentication is delegated to Adobe IMS (Identity Management System). The Worker acts as an OAuth server to MCP clients (via @cloudflare/workers-oauth-provider) and as an OAuth client to Adobe IMS upstream. Adobe tokens never reach the MCP client — they are stored encrypted in the grant and surfaced to the server as this.props.

Tools

Hierarchy: account → workspace → project → folder → files (and version stacks). ~70 tools covering most of the V4 SDK surface, by area:

Account context

Tools operate on a single active account held in durable session state, so they don't take an account_id argument. When you have one account it is resolved and remembered automatically; with several, tools error until you call `set_account` (list_accounts to discover, get_account to see the current one).

Pagination

List tools accept page_size (1–100) and after (opaque cursor); responses are { items, next_cursor } (some also has_more). Pass next_cursor as the next after.

This server mirrors the local stdio server at bowlofarugula/frameio-plugins, minus tools that require a local filesystem (upload_file, download_file, add_comment_attachment — all read/write a local path). Use remote_upload to ingest from a URL, and show_file with include=media_links.original to get a download URL.

Architecture

MCP client ──/authorize──▶ Worker (redirect_uri allowlist → approval dialog, CSRF + state→KV)
           ──302──▶ Adobe IMS /ims/authorize/v2 (user signs in with Adobe ID, consents)
IMS ──/callback──▶ Worker (validates state) ──POST /ims/token/v3──▶ access + refresh tokens
Worker ──completeAuthorization({ props })──▶ 302 back to MCP client with an MCP auth code
MCP client ──/token──▶ Worker (workers-oauth-provider) ──▶ MCP bearer token
MCP client ──/mcp (bearer)──▶ McpAgent: props decrypted into this.props, Frame.io SDK calls

• Token TTL tracks Adobe's expires_in.
• On MCP refresh, the Worker refreshes against IMS in lock-step. IMS **rotates the

refresh token on every refresh**, and the new one is persisted via newProps. An IMS refresh failure throws invalid_grant, forcing the client to re-authenticate.

Access control (portal lockdown)

/authorize is gated by `PORTAL_REDIRECT_URI` — a comma-separated allowlist of redirect URIs. Only an authorize request whose redirect_uri is on the list may start the Adobe sign-in flow; everything else is refused with 403. This stops the public *.workers.dev URL from being used to bypass an upstream gateway — e.g. a Cloudflare MCP server portal that front-ends the Worker and authenticates users before forwarding requests.

• It holds even though Dynamic Client Registration is open: an attacker can claim an

allow-listed redirect, but the OAuth code is delivered to that redirect — the gateway's callback — so they never receive it.

• Fail-closed: if PORTAL_REDIRECT_URI is unset/empty, every /authorize is refused.
• It's a non-secret value, so it ships as a vars entry in wrangler.jsonc. The default is

Cloudflare Access's portal callback (https://oauth-callbacks.cloudflareaccess.com/cdn-cgi/access/outbound-oauth-callback).

• Per-user Adobe OAuth is unaffected — each user still signs into their own Adobe identity

through the gateway.

To allow a direct client (the MCP Inspector, scripts/e2e.py, or a deployment with no portal), add that client's redirect to the list: for local wrangler dev, override it in .dev.vars (e.g. PORTAL_REDIRECT_URI=http://localhost:6274/oauth/callback); for a deployment, edit the vars entry in wrangler.jsonc.

Adobe Developer Console setup

1. Create a project at <https://developer.adobe.com/console> and add the Frame.io API.
2. Add an OAuth Web App credential (this is the only user-auth credential type that is

a confidential client and issues refresh tokens via offline_access).

1. Set the Redirect URI to your deployed callback (HTTPS, must match exactly):

   https://frameio-mcp.<your-subdomain>.workers.dev/callback

1. Scopes: openid, email, profile, offline_access, additional_info.roles. If IMS returns

invalid_scope, copy the scope string verbatim from the credential's Scopes tab.

1. While the project is In Development, only allow-listed beta-user emails can sign in —

add the testers under the project's user access settings.

Gotcha: a mismatched redirect URI does not error — IMS silently redirects to the credential's Default Redirect URI. Make sure the callback above is registered.

Deploy

npm install
cp .env.example .env            # your local, non-secret config (git-ignored)

# 1. KV namespace — create one and put its id in .env as OAUTH_KV_ID
#    (the committed wrangler.jsonc keeps a <your-kv-namespace-id> placeholder;
#     `npm run dev`/`deploy` inject your id into a generated config):
npx wrangler kv namespace create OAUTH_KV

# 2. Secrets (stored as Worker secrets, never in the repo):
npx wrangler secret put ADOBE_CLIENT_ID
npx wrangler secret put ADOBE_CLIENT_SECRET
openssl rand -hex 32 | npx wrangler secret put COOKIE_ENCRYPTION_KEY

# 3. Deploy:
npm run deploy

The deployed URL is https://frameio-mcp.<your-subdomain>.workers.dev. Confirm it matches the Adobe credential's redirect URI (…/callback); if not, update the credential (editable while In Development).

Before exposing the deployment, review `PORTAL_REDIRECT_URI` in wrangler.jsonc — it allow-lists which redirect_uris may sign in (see Access control). The default locks the Worker to a Cloudflare MCP portal; set it to your client's redirect to connect directly.

First-time accounts: if wrangler deploy reports "You need a workers.dev subdomain", open the Cloudflare dashboard → Workers & Pages once to create the subdomain, then redeploy.

Local development

cp .env.example .env             # OAUTH_KV_ID + FRAMEIO_MCP_BASE (git-ignored)
cp .dev.vars.example .dev.vars   # the three secret values (git-ignored)
npm run dev

Connecting a client

• MCP endpoint: https://frameio-mcp.<your-subdomain>.workers.dev/mcp (Streamable HTTP;

a legacy SSE endpoint is at /sse).

• The server supports Dynamic Client Registration (/register), so clients like the

MCP Inspector and Claude can register automatically.

• Sign-in is gated by PORTAL_REDIRECT_URI (see

Access control): a client can only complete the Adobe flow if its redirect_uri is allow-listed. As shipped that's the MCP portal's callback — so connect through the portal, or allow-list your client's redirect to connect directly. The two flows below are direct, so they need their redirect on the list.

MCP Inspector

npx @modelcontextprotocol/inspector@latest

Connect to the /mcp URL. You'll be taken through registration → the approval dialog → Adobe sign-in, then returned with a token. Try whoami, then list_accounts → set_account → list_workspaces → list_projects.

Headless verification

scripts/e2e.py drives the whole flow without an MCP client: it DCR-registers, prints an authorize URL to open + sign in, captures the redirect on a local listener, exchanges the code for an MCP token, then runs the MCP handshake and calls the read tools against live data. It caches the token at /tmp/mcp_token.json so you can re-run individual tools without signing in again. It reads FRAMEIO_MCP_BASE from .env (or the environment):

python3 scripts/e2e.py                        # full flow (opens a URL to sign in)
python3 scripts/e2e.py call                   # re-run the read suite with the cached token
python3 scripts/e2e.py call whoami '{}'       # call one tool with JSON args

Scripts

Notes

• The frameio package's ESM entry has an unresolved re-export; wrangler.jsonc aliases

frameio to its CJS build so esbuild can bundle it.

• V4 has no "default account" concept (whoami carries no account_id, and every API

path is account-scoped), so the active account is a convenience layer this server adds: it's resolved from list_accounts and held in the McpAgent's durable state by set_account. See Account context above.

Security

Adobe tokens are never returned to MCP clients — they live encrypted in the OAuth grant and surface to the Worker only as this.props. Secrets (ADOBE_CLIENT_SECRET, COOKIE_ENCRYPTION_KEY) are Cloudflare Worker secrets, never committed. See SECURITY.md for the threat model and how to report a vulnerability.

Support & contributing

Best-effort maintenance — I'll do my best to fix bugs and security issues, and contributions are very welcome. Open an issue or a pull request; help with docs, tests, or features is encouraged. See CONTRIBUTING.md.

Disclaimer

This is an unofficial, community-built integration. It is not affiliated with, endorsed by, or supported by Adobe or Frame.io. "Frame.io" and "Adobe" are trademarks of their respective owners and are used here only to describe what this tool connects to. Use it in accordance with Frame.io's API terms.

License

Apache-2.0 © 2026 Ian McDonald