MCP tools

Every tool the Media Ops MCP server exposes, generated from the server's own tool catalog. Server: https://media.ops.infotrafego.com.br/api/mcp (Streamable HTTP, OAuth 2.1 or API key). To connect a client, see Connect via MCP.

• Tool names are Portuguese identifiers; they are stable and are what your client calls.
• A client only sees the tools its permissions allow (scope and role).
• Results and error messages (user_message) are in Brazilian Portuguese.
• Each tool runs the same server-side service as its REST equivalent, linked below, where the full request schema lives.

Summary

quem_sou_eu

Who am I. Shows the authenticated user, role (admin/member), channel (OAuth or API key) and available permissions.

• Permission: Any authenticated user
• Type: Read-only
• REST equivalent: GET /me

No input.

listar_clientes

List clients. Lists the active clients (id and name). First step to pick client → Business Manager → ad account.

• Permission: clients:read — Read clients, Business Managers, ad accounts and assets
• Type: Read-only
• REST equivalent: GET /clients

No input.

listar_bms

List a client's Business Managers and assets. Lists a client's Business Managers with their synced assets (usable ad accounts, pages, Instagram, pixels, WhatsApp). Each Business Manager's id is the business_manager_id used in selection by the other tools.

• Permission: clients:read — Read clients, Business Managers, ad accounts and assets
• Type: Read-only
• REST equivalent: GET /clients/{id}/businesses

cadastrar_cliente

Register client and Business Manager. Registers (or updates) a client, its Business Manager and the Business Manager's Meta token. Then run sincronizar_ativos_bm.

• Permission: clients:write — Register clients and Business Managers, sync assets, enable/disable ad accounts and archive clients (archiving requires an administrator)
• Type: Writes (creates or changes data)
• REST equivalent: POST /clients

sincronizar_ativos_bm

Sync Business Manager assets. Re-reads the Business Manager's ad accounts, pages, Instagram accounts, pixels and WhatsApp numbers from Meta.

• Permission: clients:write — Register clients and Business Managers, sync assets, enable/disable ad accounts and archive clients (archiving requires an administrator)
• Type: Writes (creates or changes data)
• REST equivalent: POST /businesses/{id}/sync

ativar_desativar_conta

Enable/disable ad account. Manually enables or disables an ad account of the Business Manager (a disabled account leaves balance monitoring and the pickers).

• Permission: clients:write — Register clients and Business Managers, sync assets, enable/disable ad accounts and archive clients (archiving requires an administrator)
• Type: Writes (creates or changes data)
• REST equivalent: PATCH /businesses/{id}/ad-accounts

arquivar_cliente

Archive client (offboarding). Archives the client: removes the Meta tokens and clears the Business Managers' assets. Administrators only.

• Permission: clients:write (administrators only) — Register clients and Business Managers, sync assets, enable/disable ad accounts and archive clients (archiving requires an administrator)
• Type: Destructive (the client asks for confirmation)
• REST equivalent: POST /clients/{id}/archive

listar_saldos

Ad account balances. Available balance, average daily spend and days left for the monitored ad accounts (prepaid/Pix accounts).

• Permission: balances:read — Read ad account balances
• Type: Read-only
• REST equivalent: GET /account-balances

No input.

atualizar_saldos

Refresh balances. Queries Meta and refreshes the balances panel.

• Permission: balances:write — Refresh ad account balances
• Type: Writes (creates or changes data)
• REST equivalent: POST /account-balances/refresh

buscar_publicos

Search audiences, interests and locations. Queries Meta on the selected ad account. search_type: "audiences" (custom audiences — use only the ones with usable=true; paged: limit, default 50, and after = paging.after of the previous page; saved audiences only with include_saved=true), "interests" (query), "interest_suggestions" (interest_list: a list of names, e.g. ["Medical residency"]), "geo" (query + location_types; Meta may include subcities and neighborhoods — filter on the type field) or "validate_audiences" (audience_ids). The job_id in the response only groups this lookup's request logs (use it with logs_execucao); it is not a campaign execution.

• Permission: meta:read — Query Meta and Google Drive: audiences, interests, locations, lead forms, posts, campaigns, ad sets and folders
• Type: Read-only
• REST equivalent: POST /meta/audiences/search

buscar_formularios

Search lead forms. Lists the lead generation forms of the selected page — needed for the native lead form objective. The job_id in the response only groups this lookup's request logs (use it with logs_execucao); it is not a campaign execution.

• Permission: meta:read — Query Meta and Google Drive: audiences, interests, locations, lead forms, posts, campaigns, ad sets and folders
• Type: Read-only
• REST equivalent: POST /meta/leadforms/search

buscar_publicacoes

Search Instagram posts. Lists or searches posts of the selected Instagram account (action "list", "search" by text/permalink or "get" by post_id) to advertise existing posts. The job_id in the response only groups this lookup's request logs (use it with logs_execucao); it is not a campaign execution.

• Permission: meta:read — Query Meta and Google Drive: audiences, interests, locations, lead forms, posts, campaigns, ad sets and folders
• Type: Read-only
• REST equivalent: POST /meta/posts/search

buscar_campanhas

Search existing campaigns. Lists the campaigns of the selected ad account (to extend an existing campaign or ad set), newest first. Paged: limit (default 50, max 100) and after = paging.after of the previous page; paging.has_more tells whether there is more. effective_status: ACTIVE, PAUSED, WITH_ISSUES (default), ARCHIVED, DELETED, IN_PROCESS. The job_id in the response only groups this lookup's request logs (use it with logs_execucao); it is not a campaign execution.

• Permission: meta:read — Query Meta and Google Drive: audiences, interests, locations, lead forms, posts, campaigns, ad sets and folders
• Type: Read-only
• REST equivalent: POST /meta/campaigns/search

buscar_conjuntos

Search ad sets. Lists the ad sets of a campaign (campaign_id) or of the whole selected ad account. effective_status: ACTIVE, PAUSED, WITH_ISSUES (default), CAMPAIGN_PAUSED, ARCHIVED, DELETED, IN_PROCESS. The job_id in the response only groups this lookup's request logs (use it with logs_execucao); it is not a campaign execution.

• Permission: meta:read — Query Meta and Google Drive: audiences, interests, locations, lead forms, posts, campaigns, ad sets and folders
• Type: Read-only
• REST equivalent: POST /meta/adsets/search

escanear_pasta_drive

Scan a Google Drive folder. Lists the media in a Drive folder the way the campaign creator sees it: loose images/videos become creatives, a CARROSSEL subfolder becomes carousels, FEED/STORIES folders become placement asset customization. Send folder_url OR feed_folder_url + stories_folder_url (links like https://drive.google.com/drive/folders/<ID>). The job_id in the response only groups this lookup's request logs (use it with logs_execucao); it is not a campaign execution.

• Permission: meta:read — Query Meta and Google Drive: audiences, interests, locations, lead forms, posts, campaigns, ad sets and folders
• Type: Read-only
• REST equivalent: POST /drive/scan

validar_campanha

Validate campaign (dry run). Builds and validates a campaign with the SAME rules as the web app, creating nothing on Meta. Returns per-field errors and a preview of the ad sets and ads. Use it before criar_campanha.

• Permission: campaigns:write — Create, extend and retry campaigns (everything is created PAUSED)
• Type: Read-only
• REST equivalent: POST /campaigns/validate

criar_campanha

Create campaign. Creates campaign → ad sets → creatives → ads on Meta, everything PAUSED, with the same rules and orchestration as the web app (audience pre-flight, Meta rate limits, reuse on retries). Also extends campaigns (mode extend_campaign) and ad sets (extend_adset). Runs in the background: poll status_execucao with the returned job_id until the status is success, partial or error.

• Permission: campaigns:write — Create, extend and retry campaigns (everything is created PAUSED)
• Type: Writes (creates or changes data)
• REST equivalent: POST /campaigns

status_execucao

Execution status. Progress of a campaign creation run (job_id from criar_campanha/reexecutar_execucao): overall status, step by step (campaign, ad sets, uploads, creatives, ads) and pauses caused by Meta rate limits. The step list stays available after the run ends.

• Permission: campaigns:read — Read campaign executions, progress and logs
• Type: Read-only
• REST equivalent: GET /executions/{id}/progress

detalhar_execucao

Execution details. Full record of the run: summary with the IDs created on Meta, errors and configuration.

• Permission: campaigns:read — Read campaign executions, progress and logs
• Type: Read-only
• REST equivalent: GET /executions/{id}

listar_execucoes

List executions. Latest campaign creation runs (your own; administrators see all of them).

• Permission: campaigns:read — Read campaign executions, progress and logs
• Type: Read-only
• REST equivalent: GET /executions

logs_execucao

Execution logs. Calls made to Meta/Drive during a run or a lookup (also accepts the job_id returned by buscar_*), with error messages in Portuguese and Meta error codes. Retention: successful calls are kept for 24h and errors for 14 days; after that the list comes back empty — the run's outcome stays in detalhar_execucao.

• Permission: campaigns:read — Read campaign executions, progress and logs
• Type: Read-only
• REST equivalent: GET /executions/{id}/logs

reexecutar_execucao

Retry execution. Smart retry: redoes only what failed, reusing the campaign, ad sets, media, creatives and ads already created. Runs in the background: poll status_execucao with the returned job_id until the status is success, partial or error.

• Permission: campaigns:write — Create, extend and retry campaigns (everything is created PAUSED)
• Type: Writes (creates or changes data)
• REST equivalent: POST /executions/{id}/retry

reexecutar_log

Retry a single call. Repeats one failed call (by log id). Idempotent: two requests never create the same item twice.

• Permission: campaigns:write — Create, extend and retry campaigns (everything is created PAUSED)
• Type: Writes (creates or changes data)
• REST equivalent: POST /logs/{id}/retry

criar_publicos_engajamento

Create engagement audiences. Creates the default engagement audiences (Instagram and Facebook, 365 or 730 days) on the selected ad account. Track it with status_publicos.

• Permission: audiences:write — Create engagement audiences
• Type: Writes (creates or changes data)
• REST equivalent: POST /audiences/engagement

status_publicos

Audience creation status. Result of an engagement audience creation run.

• Permission: audiences:read — Read audience creation runs
• Type: Read-only
• REST equivalent: GET /audience-executions/{id}

listar_execucoes_publicos

List audience creation runs. Latest engagement audience creation runs.

• Permission: audiences:read — Read audience creation runs
• Type: Read-only
• REST equivalent: GET /audience-executions

No input.

listar_modelos_segmentacao

List targeting templates. Targeting templates saved by the team. Use the id in adsets[].targeting_template_id when creating campaigns.

• Permission: templates:read — Read targeting templates
• Type: Read-only
• REST equivalent: GET /targeting-templates

No input.

criar_modelo_segmentacao

Create targeting template. Saves a targeting (the creator's internal format: age, genders, locations, interests, audiences) as a team template.

• Permission: templates:write — Create, rename and delete targeting templates
• Type: Writes (creates or changes data)
• REST equivalent: POST /targeting-templates

renomear_modelo_segmentacao

Rename targeting template. Changes a template's name/description (author or administrator only).

• Permission: templates:write — Create, rename and delete targeting templates
• Type: Writes (creates or changes data)
• REST equivalent: PATCH /targeting-templates/{id}

remover_modelo_segmentacao

Delete targeting template. Deletes a template (author or administrator only).

• Permission: templates:write — Create, rename and delete targeting templates
• Type: Destructive (the client asks for confirmation)
• REST equivalent: DELETE /targeting-templates/{id}

listar_notificacoes

Notifications. Your recent notifications (finished campaigns, failures, syncs).

• Permission: Any authenticated user
• Type: Read-only
• REST equivalent: GET /notifications

No input.

listar_usuarios

List users. Team users. Administrators only.

• Permission: admin:users (administrators only) — Manage team users (administrators only)
• Type: Read-only
• REST equivalent: GET /users

No input.

criar_usuario

Create user. Creates a team user (public sign-up is disabled). Administrators only.

• Permission: admin:users (administrators only) — Manage team users (administrators only)
• Type: Writes (creates or changes data)
• REST equivalent: POST /users

atualizar_usuario

Update user. Changes a user's name or role (admin/member). Administrators only.

• Permission: admin:users (administrators only) — Manage team users (administrators only)
• Type: Writes (creates or changes data)
• REST equivalent: PATCH /users/{id}

remover_usuario

Delete user. Deletes a user. Administrators only.

• Permission: admin:users (administrators only) — Manage team users (administrators only)
• Type: Destructive (the client asks for confirmation)
• REST equivalent: DELETE /users/{id}