# Lena > Lena bulk-uploads Meta (Facebook / Instagram) ad creative - both images and videos - through a remote MCP server. Uploads go into an organization's shared library; requests address each connected Facebook ads account by the `workspaceId` that `list_ad_accounts` gives it, and people know it by its name and `act_…` id. Claude, Claude Code, Codex, and any other MCP host connect to the same URL with OAuth. To set up Lena or connect its MCP server, read [https://www.letlena.com/setup.md](https://www.letlena.com/setup.md) and follow it. ## How the tools work - Everything belongs to an organization: its uploads, share links, library and brand research are shared with everyone in it. A connection can work in every organization the person belongs to: tools take an optional `organizationId` and, without one, work in that app's default organization. `list_organizations` lists them all and marks the default `isDefault`. Someone with one organization is asked only when a tool says to. With several and no default, ask at the start of each chat which one to use and pass its `organizationId` on every call in that chat. Once a call's organization is known, its result starts with `organization`, the one it ran in: if that is not the one this chat is using, call again with its `organizationId`. When the person picks or switches organization in a chat, offer once to make it the default: `set_default_organization` sets it for that app, in later chats too, and is called only when they agree. A tool that answers `organization_required`, `default_organization_removed` or `organization_access_denied` lists their organizations: ask which one to use, even if only one is listed. - Rows say who added them, as a user id: `uploadedBy` on uploads, `requestedBy` on brand research. To see one person's, pass `"me"` or a `userId` from `list_organization_members` as `uploadedBy` to `list_upload_batches` / `list_upload_content`, or as `requestedBy` to `get_brand_research` with no `jobId`. - Tools that act in a Meta ad account take its `workspaceId` from `list_ad_accounts`, which lists only this organization's. The `workspaceId` is for requests only: when talking to the person, name an ad account by its name and `act_…` id, never by its `workspaceId`, and never call it a workspace. If `list_ad_accounts` is empty, it returns the setup link: give it to the person when they ask to connect Meta or need an ad account — not before. If an ad account's `metaConnection.status` is not `healthy` (token expired, revoked or missing permissions), its `metaConnection.reconnect` gives its token holder the fix, and `metaConnection.canReconnect` only says whether this person can reconnect it; offer the fix when a tool on that ad account fails with `meta_token_invalid` / `meta_not_connected` or they ask. - The one-at-a-time `create_meta_adcreative` and `create_meta_ad` are deprecated (use `create_meta_adcreatives` and `create_meta_ads`): still accepted until 2026-11-15, and results from them carry a `deprecated` notice naming the replacement. - When the person asks to upload image or video files, or shares them while talking about their ads, Meta or Lena, offer to upload them with Lena ("Do you want to upload these files with Lena?"). Videos are accepted just like images, and one batch can hold both. - MCP tools never carry file bytes. `create_upload_batch` returns presigned storage destinations plus a server-signed `plan`, the hosted `uploader` (`/mcp/uploader/v4.mjs`, Node 20+) that executes it, and `nextActions`, the steps the upload still needs, in order, with the ids each takes. - Capability test before opening a batch: direct upload only if you can read each file's bytes from its local path AND run the uploader with Node 20+ (without Node, a file qualifies only if you send it yourself: a `PUT` destination with its headers, a `MULTIPART` one through `sign_upload_parts`, a PUT per part with its signed headers only, and `complete_upload`; pass `includeDestinations: true` to `create_upload_batch` to get each `url` and its headers). A shell without access to the attachment's path does not qualify. - If `create_upload_batch` refuses the manifest, the refusal carries the organization's upload `limits`; fix the list and retry. - Before opening a batch for the uploader, tell the person you will download Lena's upload script and run it with Node on their machine, and go ahead only if they agree; if they decline, send the files yourself as without Node, or if you cannot, use `create_upload_share_link` for them. - Direct path: write `plan.json` as `{ batch: , files: [{ contentId, localPath }] }` (never edit the plan; `localPath` is the only field you add; match by `contentId`), then `node extuitive-upload.mjs plan.json`. It sends every file, multipart included, waits for each to be accepted or rejected, and prints one JSON report within `--wait-seconds` (default 100). Exit `0`: every file `READY`; `1`: a file was `REJECTED` or failed; `2`: the plan was refused; `3`: still in progress, run it again (finished work is skipped). Delete `plan.json` and any checkpoint files afterwards. - Files that fail the test: an owner or admin of the organization calls `create_upload_share_link` once for them and you show the returned `url` in the conversation verbatim, then poll `get_upload_share_link` until `terminal`. There is no other page to send anyone to. - Without the uploader, poll `list_upload_content` with the `batchId` and `summaryOnly: true` until the batch is `settled`, `suggestedPollSeconds` apart; a host that cannot pause passes `waitSeconds` and the server waits for it. `READY` is the only status that means a file was accepted; `VALIDATING` means still being checked. - Uploads land in the organization's library and, when the organization has exactly one connected Meta ad account the uploader can act in, in that ad account too: `create_upload_batch` and `create_upload_share_link` default to it, `publishToWorkspaceIds: []` keeps the files out of Meta, and the result says where they go (`publishTargets` on a batch, `adAccount` on a link). With several ad accounts, a file reaches one only through `publishToWorkspaceIds` or a later `send_uploads_to_meta`; ask the person first, and which one. Its image hash or video id for ads there is on `metaPublishSummary.forWorkspace` of a row read with that `workspaceId`, once `PUBLISHED`. That is the only way `create_meta_adcreatives` takes media (a URL only as a video's thumbnail, its `videoThumbUrl`), and `create_meta_ads` takes its creative only as `{ "creative_id": "…" }`. - Tool groups: organizations and ad accounts (`list_organizations`, `set_default_organization`, `list_organization_members`, `list_ad_accounts`, `get_credit_balance`), uploads (`create_upload_batch`, `sign_upload_parts`, `complete_upload`, `list_upload_batches`, `list_upload_content`, `get_upload_content`, `send_uploads_to_meta`), share links (`create_upload_share_link`, `send_upload_share_link_email`, `get_upload_share_link`, `revoke_upload_share_link`), content library (`describe_creative`, `group_aspect_ratio_variants`, `search_creative`), Meta objects (`create_meta_campaign`, `create_meta_adset`, `create_meta_adcreatives`, `create_meta_ads`, `update_meta_object`, `get_meta_actions`, `list_meta_objects`, `get_meta_ad_config`, `start_meta_ad_config_audit`, `get_meta_ad_config_audit`, `get_meta_ad_identities`, `get_meta_pixel_health`, `get_meta_insights`, `list_meta_audiences`, `get_meta_audience`, `search_meta_targeting`, `estimate_meta_reach`, `create_meta_custom_audience`; where enabled, `prepare_meta_ads_import`), lead forms (`create_meta_lead_forms`, `update_meta_lead_form`, `list_meta_lead_forms`, `get_meta_lead_form`, `list_meta_leads`), brand research (`start_brand_research`, `get_brand_research`; or, where voice of customer research is enabled, `start_voice_of_customer_research`, `get_voice_of_customer_research`, `read_voice_of_customer_research_file`, `get_voice_of_customer_style_guide` in their place), and support (`contact_support`). - Performance freshness: `get_meta_insights` reads Meta live when called (`datePreset` `today`, `yesterday`, `last_7d`, `last_30d` or `last_90d`; only `today` includes the current day; `dateFrom` and `dateTo` pick any other window) and returns `fetchedAt`. For current or up-to-date numbers the agent uses `get_meta_insights` rather than a spreadsheet, export or other copy of Meta's numbers, which can be days or weeks old. - Creatives, ads and lead forms go in batches: `create_meta_adcreatives`, `create_meta_ads` and `create_meta_lead_forms` take up to 50 in one call (`items`, each with its own `clientToken`) and answer with a row per item, and `get_meta_actions` with `actionIds` polls up to 50 at once. Every item is checked before any is sent, and the batch is queued in one request; Meta checks each item when it runs, so its refusal arrives on the poll as `FAILED`. A refused or failed item goes again with corrected params and a new `clientToken`. The agent makes these calls itself, in the conversation, not through a subagent or background agent, and when the host refuses one it stops and tells the person. - Ad creatives: `create_meta_adcreatives` sends every Advantage+ creative enhancement, multi-advertiser ads and personalized destinations as `OPT_OUT` unless the call opts in. The agent asks the person once per request whether they want any of them on, and opts in only what they confirm. If the person is unsure, the agent can read which enhancements their recent ads use (`list_meta_objects` with `includeCreative` and `includeEnhancements`, off by default because Meta lists every feature) and suggest those. - Renaming and editing: for every connection, `update_meta_object` renames a campaign, ad set or ad (`params.name`), changes who an ad set reaches (`params.targeting`: only the keys to change, among its audiences, exclusions, interests, ages and locations) or swaps the creative an ad shows (`params.creative`, as `{ "creative_id": "…" }`), each sent on its own. Each runs at once and needs no approval. A rename changes nothing about delivery or spend; a targeting change or a creative swap applies to a running ad set or ad too, so the agent changes only what the person asked for. An ad's copy, link and URL parameters belong to its creative, which is never rewritten: the agent creates a new creative with the change (`create_meta_adcreatives`) and swaps it in. - Lead ads: an Instant Form is on a Facebook Page, so the lead form tools also take a `pageId`, one of the Pages `get_meta_ad_identities` lists with `pageSource: "ad_account"`. `create_meta_lead_forms` creates forms (each item names its own Page); Meta changes nothing on a form once it exists except its status, so the agent confirms the questions, the business's privacy policy URL and the thank-you page's `website_url` (Meta refuses a new form without one) with the person first, and changes a form by copying `get_meta_lead_form`'s `cloneParams` into a new one. `update_meta_lead_form` archives a form or puts it back in use, at once and without approval. A form runs in an `OUTCOME_LEADS` campaign whose ad set has `optimization_goal: "LEAD_GENERATION"`, `destination_type: "ON_AD"` and `promoted_object.page_id`, through a creative that names the form's id as `call_to_action.value.lead_gen_form_id`; a build creates the forms with the campaign, and the creatives once each form has settled. `list_meta_leads` reads what people sent through a form: leads are personal data, so the agent reads them only when the person asks, shows them only to that person, and puts them nowhere else unless asked. Lena does not keep them, and Meta keeps them for 90 days. Lead forms need the Meta connection to grant `pages_manage_ads`, `pages_read_engagement` and `leads_retrieval`; a connection made before them fails with `meta_permission_missing` until its token holder reconnects Meta, and reading leads can also need access in the Page's Leads Access Manager. - Live ads (offered to some organizations for now; only where it is enabled does `update_meta_object` take `status` and budgets, and the server accept `status: "ACTIVE"` on `create_meta_ads`, and on `create_meta_campaign` or `create_meta_adset` without a budget of its own). A campaign or ad set that holds its own budget is always created `PAUSED`; when the person asks, `update_meta_object` turns a campaign, ad set or ad on or off, or changes a campaign's or ad set's budget. To build something live, the agent creates the campaign `ACTIVE`, the ad sets `PAUSED` and the ads `ACTIVE` when the ad sets hold the budget, or the campaign `PAUSED` and the ad sets and ads `ACTIVE` when the campaign holds it; once every create has settled, it turns on what holds the budget with `update_meta_object`, and if any create failed it turns nothing on. An ad delivers only while it, its ad set and its campaign are all `ACTIVE`: a result names any paused parent in `delivery.blockedBy`, and the agent tells the person instead of turning the parent on. A budget change, or turning on a campaign or ad set that holds a budget, waits at `PENDING_APPROVAL` until someone approves it on the ad account's approvals page in Lena, which the result links as `approval.url`. A paused campaign whose ad sets hold their own budgets is never turned on here: the refusal, `turn_on_in_ads_manager`, says why and links the campaign in Ads Manager (`adsManagerUrl`), and that campaign's `delivery.blockedBy` entry carries the same reason as `adsManagerReason`. Where live ads are not enabled, everything is created `PAUSED` and the person turns it on in Ads Manager. - Brand research (offered to some organizations for now; the server lists these tools only where it is enabled) is consumer research for a brand, product line or product: a scanned brand site, verified customer quotes, competitor ads as execution references, rendered as an HTML deck and a PDF with the evidence kept alongside. A new run spends the organization's credits (a cached or in-flight run costs nothing). It takes no ad account and needs no Meta connection; it is shared with the organization and cached per organization, brand domain and scope. A new run takes 20 to 40 minutes, so call `get_brand_research` with no `jobId` first (it lists past runs; starting a run already in flight returns it with `inFlight: true`) and never pass `refresh: true` without the person asking for fresh research. Poll `get_brand_research` at `suggestedPollSeconds` until `terminal`; the artifact links are presigned and expire. - Voice of customer research (offered to some organizations for now; where enabled it replaces `start_brand_research` and `get_brand_research`) is research a person comes back to, organized as projects: verified customer quotes from Reddit, reviews and forums, grouped into the patterns that repeat, with no competitor ads and no deck. Call `get_voice_of_customer_research` with no `projectId` first to offer continuing an existing project. Before `start_voice_of_customer_research`, ask what to research (when the person names a brand without its website, suggest the URL you believe is its homepage and have them confirm or correct it), what the person wants to learn (`focus`) and any other guidance (`notes`), and suggest a `projectName`, so the research sets off in the right direction. The research is interactive: follow a run with `get_voice_of_customer_research` (`projectId`, `since` = `conversation.messagesNext` from the last read, `waitSeconds`) until `terminal` without ending your turn, pass on its messages as written as Lena's words, and send the person's answers to its questions and any redirection as `request` on `start_voice_of_customer_research` with the `projectId`. A run takes at least 10 minutes. A background run is not followed: schedule a follow-up for yourself (a timer, a scheduled task, a wake-up or a loop) at 10 minutes and every 5 after that until it finishes, or, if you cannot, tell the person to ask you for an update. When it finishes, its `summary` is Lena's finished research report, not a status update: present it to the person as the report, and answer from the files `read_voice_of_customer_research_file` returns, quoting customers verbatim. To change or deepen the research, continue the project (`start_voice_of_customer_research` with `projectId` and `request`), which resumes the original research from its latest finished run. Every run is a numbered version (v1, v2, …) and `latestVersion`, the newest that finished, is what reads and continuations default to; `read_voice_of_customer_research_file` with `version` opens an earlier one, and `fromVersion` on a continuation goes back and builds on it. Projects record who started each run (`createdBy`, `updatedBy`, each run's `requestedBy`, with names). For a formatted version, `get_voice_of_customer_style_guide` gives the house look to build one from the files. - Competitor ads research (offered to some organizations for now; the server lists these tools only where it is enabled) shows what competitors' ads look like, organized as projects like voice of customer research: the competitors that are active, the angles, hooks, formats and visual codes that repeat, with the ads as references. The ads are execution references that show what ran, never what worked: never call one a winner. Call `get_competitor_ads_research` with no `projectId` first to offer continuing an existing project. `start_competitor_ads_research` takes the same intake as voice of customer research (`projectName`, `brandUrl`, `scope`, `scopeName`, `focus`, `notes`, `runMode`) plus optional `competitors` (competitor brand names to include) and `vocProjectId` (a finished voice of customer project, from `get_voice_of_customer_research`, whose findings shape the search). Follow and steer a run, and continue a project with `projectId` and `request` (a continuation may replace `competitors`), exactly as for voice of customer research, with `get_competitor_ads_research`. Read the report with `read_competitor_ads_research_file`; an image path returns a link (`url`, `contentType`, `expiresAt`) to show the creative from, and the link expires. `search_competitor_ads` searches the ads every finished competitor ads project in the organization found: `query` for what they show, `similarTo` (an `assetSha256` from a result) for look-alikes, or neither for the newest, narrowed by `brandNames`, `projectIds`, `relationships`, `platforms`, `spyglassAdFormats`, `spyglassCategories`, `active` and `minDaysRun`, and listed by `sortBy` (`recent`, `impressionPercentile`, `daysRun` or `viewCount`) when there is no `query` or `similarTo`; each ad has a `previewUrl` to show it from, an `adUrl` to the ad where it ran, a `spyglassUrl` to it in Spyglass, and its run dates, and Spyglass's own format, hook and angle labels (`spyglass*` fields, alongside our own analysis). `impressionPercentile` ranks an ad among the same brand's ads from the same period: compare within a brand, never across brands. - `contact_support` emails the Lena support team; the server adds who the person and organization are, so nothing about them goes in the arguments. `kind` says what is being reported (`bug`, `friction`, `feature_request`, `question`) and `initiatedBy` says who decided to file (`person`, `agent`). Nothing is filed without the person's agreement: when a tool fails in a way the person cannot fix, or works but is confusing or slow, offer to report it as a `bug` or `friction`, once per distinct problem, and file only if they agree; file a `feature_request` or `question` only when the person wants it sent. Every failed tool result carries a `requestId` to quote in the report; a failure on Lena's side also carries `retryable` and a `support` field suggesting a report to offer. Limited to 5 reports per person per hour. ## Docs - [Setup playbook for agents](https://www.letlena.com/setup.md): how to add the MCP server in each host and sign in - [Setup guide for people](https://www.letlena.com/support): Claude Desktop and Codex steps, what happens after an upload, and troubleshooting, written for the person you are helping - [MCP endpoint](https://www.letlena.com/mcp): Streamable HTTP, OAuth 2.1 + PKCE + DCR - [OAuth protected resource metadata](https://www.letlena.com/.well-known/oauth-protected-resource): RFC 9728 - [OAuth authorization server metadata](https://www.letlena.com/.well-known/oauth-authorization-server): RFC 8414 ## Optional - [Website](https://www.letlena.com): marketing home and sign-in - [Terms](https://www.letlena.com/terms) - [Privacy policy](https://www.letlena.com/privacy) - [Data deletion](https://www.letlena.com/data-deletion): disconnect Meta and request deletion of your data - Support: support@letlena.com