# Run multi-client agency operations

Source: https://developers.tokportal.com/agents/for/agency-multi-client/
Markdown: https://developers.tokportal.com/agents/for/agency-multi-client.md

An agency using any MCP-capable agent with TokPortal runs every client through the same four primitives — bundles, accounts, videos, webhooks — and keeps them separate with `external_ref` and account filters. `create_bundles_bulk` opens a client's fleet in their market, `list_bundles`/`list_accounts` filter by client reference, `videos_only` bundles carry each month's content onto delivered accounts, `create_webhook_endpoint` pushes `account.banned` and `video.finalized` into the agency's tooling, and `export_analytics_videos` / `create_analytics_report` produce the client deliverable. One API key, no per-client OAuth, no app audit, human-operated accounts the agency never has to log into.

## Try the workflow without spending

For this trial, use the remote MCP endpoint `https://app.tokportal.com/api/ext/mcp`, local `tokportal-mcp` **1.15.1 or later**, or the REST API. Upgrade and restart an older local server first. Version 1.15.0 does not forward the dry-run header; do not use its write tools for a simulation. If you cannot verify the installed local version, use the remote endpoint or REST.

Use the [sandbox](https://developers.tokportal.com/sandbox) for the first attempt. MCP write tools accept `dry_run: true` as a top-level argument, beside `body`; REST writes accept the `X-TokPortal-Dry-Run: true` header. Keep your usual authentication and scopes. Each simulated write validates the request and returns `credits_would_charge` with `credits_charged: 0`. Nothing is created or published.

Simulated IDs start with `00000000-0000-4000-8000-`. Use them only in later dry-run writes. GET requests read real data, so skip publish-readiness checks and polling for synthetic IDs. Simulations have no cross-call memory and upload URLs are placeholders: do not upload files to them.

To run for real, review the returned price and confirm **before the first live write**. Bundle creation charges credits immediately; publishing hands the order to a manager. Repeat creation without dry-run mode and use the new real IDs for configuration and publishing. A synthetic ID cannot be reused in a live request.

## How it works

Structure comes from `external_ref`: put the client slug in it (`acme-us`, `bloom-fr`) on every bundle — `create_bundle` and `create_bundles_bulk` both accept it, and `list_bundles?external_ref=acme-us` returns that client's work. Video slots have their own `external_ref` for creative ids. Accounts inherit their bundle; `list_account_bundles` on an account gives its history. If clients need real isolation, use one API key per client (keys are per workspace, shown once, revocable individually) — the agent can hold several and pick by client.

Monthly operations from any MCP-capable agent then look like this. Onboarding: `create_bundles_bulk` (`accounts_count`, `videos_per_account`, `country`, warming terms) plus per-account `configure_bundle_account` from the client's brand sheet. Content: `upload_video` for each asset, `batch_configure_bundle_videos` for the month at ≤3/day, `publish_bundle`. Reposting existing accounts next month: `create_bundle` with `bundle_type: videos_only` and `account_id`, `videos_quantity`, then the same batch fill. Corrections: `request_bundle_video_corrections` when the client rejects a post during the 72-hour review (`in_review`), or `finalize_bundle_video` to approve immediately; set `auto_finalize_videos: false` on bundles where the client insists on approving.

Risk and reporting: one webhook endpoint per client system with `account.banned`, `account.ban_appeal.submitted`, `account.ban_resolution.decided`, `video.finalized`; `list_account_bans` as the single source of truth for ban state and refund/remake outcomes; `create_analytics_report` (or `export_analytics_report_html`) for a branded monthly report and `export_analytics_videos` for the raw CSV. Credits are shared per workspace — `list_credit_transactions` gives the per-bundle ledger to re-invoice each client.

## Tool sequence

1. `tokportal_get_credit_costs` — Per-client quotes; contract allowances show here.
2. `tokportal_create_bundles_bulk` — Client fleet with `external_ref: <client>`.
3. `tokportal_list_bundles` — `external_ref`, `status`, `platform` filters per client.
4. `tokportal_create_bundle` — `videos_only` + `account_id` for next month's content on delivered accounts.
5. `tokportal_batch_configure_bundle_videos` — Month of slots per bundle.
6. `tokportal_request_bundle_video_corrections` — Client rejects a post in review → manager redoes it.
7. `tokportal_create_webhook_endpoint` — Per-client endpoint: `account.banned`, `account.ban_appeal.submitted`, `account.ban_resolution.decided`, `video.finalized`.
8. `tokportal_list_account_bans` — Ban lifecycle + refund/remake resolution for client comms.
9. `tokportal_create_analytics_report` — Monthly report per client (or `export_analytics_report_html`).
10. `tokportal_list_credit_transactions` — Ledger to re-invoice credits per client.

## Pick your agent

- [Run multi-client agency operations with Claude](https://developers.tokportal.com/agents/claude/agency-multi-client) — Anthropic's assistant on claude.ai, the mobile apps and Claude Desktop, with custom MCP connectors.
- [Run multi-client agency operations with Claude Code](https://developers.tokportal.com/agents/claude-code/agency-multi-client) — Anthropic's terminal coding agent; MCP servers are added with `claude mcp add` and used in any session.
- [Run multi-client agency operations with ChatGPT](https://developers.tokportal.com/agents/chatgpt/agency-multi-client) — OpenAI's assistant; plans with developer mode can add remote MCP servers as custom connectors.
- [Run multi-client agency operations with OpenAI Codex](https://developers.tokportal.com/agents/codex/agency-multi-client) — OpenAI's coding agent (Codex CLI and IDE extension); MCP servers live in `~/.codex/config.toml`.
- [Run multi-client agency operations with Cursor](https://developers.tokportal.com/agents/cursor/agency-multi-client) — AI code editor with an agent mode; MCP servers are configured in `.cursor/mcp.json` or via a one-click deeplink.
- [Run multi-client agency operations with Windsurf](https://developers.tokportal.com/agents/windsurf/agency-multi-client) — Codeium's agentic IDE (Cascade); MCP servers are declared in `~/.codeium/windsurf/mcp_config.json`.
- [Run multi-client agency operations with Cline](https://developers.tokportal.com/agents/cline/agency-multi-client) — Open-source autonomous coding agent for VS Code with an MCP marketplace and per-tool approval.
- [Run multi-client agency operations with OpenClaw](https://developers.tokportal.com/agents/openclaw/agency-multi-client) — Open-source autonomous agent runtime with a skills registry (ClawHub); TokPortal ships as a first-party skill.
- [Run multi-client agency operations with Hermes Agent](https://developers.tokportal.com/agents/hermes-agent/agency-multi-client) — Nous Research's open-source agent runtime; MCP servers are declared under `mcp_servers` in `~/.hermes/config.yaml`.
- [Run multi-client agency operations with Gemini CLI](https://developers.tokportal.com/agents/gemini-cli/agency-multi-client) — Google's open-source terminal agent for Gemini; MCP servers via `gemini mcp add` or `~/.gemini/settings.json`, plus extensions.
- [Run multi-client agency operations with Goose](https://developers.tokportal.com/agents/goose/agency-multi-client) — Block's open-source local agent; remote MCP servers are added as extensions (Streaming HTTP) or via a `goose://` deeplink.
- [Run multi-client agency operations with Perplexity](https://developers.tokportal.com/agents/perplexity/agency-multi-client) — Answer engine with custom MCP connectors on paid plans; good for read-only research over your TokPortal data.
- [Run multi-client agency operations with Microsoft Copilot Studio](https://developers.tokportal.com/agents/copilot-studio/agency-multi-client) — Microsoft's low-code agent builder; MCP servers are added as tools through the MCP onboarding wizard (Streamable transport).
- [Run multi-client agency operations with Factory Droid](https://developers.tokportal.com/agents/factory-droid/agency-multi-client) — Factory's software-engineering agent (`droid` CLI); HTTP MCP servers are added with `droid mcp add`.
- [Run multi-client agency operations with n8n](https://developers.tokportal.com/agents/n8n/agency-multi-client) — Open-source workflow automation; use the built-in MCP Client Tool node with an AI Agent, or the community node `n8n-nodes-tokportal` for deterministic steps.
- [Run multi-client agency operations with Make](https://developers.tokportal.com/agents/make/agency-multi-client) — Visual automation platform (ex-Integromat); call TokPortal from HTTP modules with `X-API-Key`, or from Make's MCP Client module where available.
- [Run multi-client agency operations with Zapier](https://developers.tokportal.com/agents/zapier/agency-multi-client) — Automation platform; today TokPortal is used via Webhooks by Zapier (REST) — a native TokPortal app is coming.
- [Run multi-client agency operations with Pipedream](https://developers.tokportal.com/agents/pipedream/agency-multi-client) — Serverless integration platform for developers; call TokPortal from a Node.js/Python code step or the HTTP action, and receive webhooks on an HTTP trigger.
- [Run multi-client agency operations with Dify](https://developers.tokportal.com/agents/dify/agency-multi-client) — Open-source LLM app platform; MCP servers are registered under Tools → MCP and used by Agent nodes and Agent apps.
- [Run multi-client agency operations with Flowise](https://developers.tokportal.com/agents/flowise/agency-multi-client) — Open-source visual builder for LLM flows; the Custom MCP node connects any Streamable HTTP server to Agentflow / tool agents.
- [Run multi-client agency operations with Langflow](https://developers.tokportal.com/agents/langflow/agency-multi-client) — Open-source visual framework for agents; the MCP Tools component connects to servers registered in Settings → MCP Servers.
- [Run multi-client agency operations with CrewAI](https://developers.tokportal.com/agents/crewai/agency-multi-client) — Python multi-agent framework; `MCPServerAdapter` from `crewai-tools` turns any MCP server into agent tools.
- [Run multi-client agency operations with LangChain](https://developers.tokportal.com/agents/langchain/agency-multi-client) — LangChain / LangGraph agents load MCP tools with `langchain-mcp-adapters` (`MultiServerMCPClient`).
- [Run multi-client agency operations with Vercel AI SDK](https://developers.tokportal.com/agents/vercel-ai-sdk/agency-multi-client) — TypeScript toolkit for AI apps; the MCP client (`@ai-sdk/mcp`, formerly `experimental_createMCPClient` in `ai`) turns TokPortal tools into `generateText`/`streamText` tools.
- [Run multi-client agency operations with Mastra](https://developers.tokportal.com/agents/mastra/agency-multi-client) — TypeScript agent framework; `MCPClient` from `@mastra/mcp` connects HTTP or stdio MCP servers and hands their tools to an `Agent`.

## Related

- [Agency multi-client playbook](https://developers.tokportal.com/use-cases/industry/agency-multi-client-management)
- [Bans & appeals](https://developers.tokportal.com/bans-and-appeals)
- [Webhooks](https://developers.tokportal.com/webhooks)
- [Analytics API](https://developers.tokportal.com/analytics)
- [MCP server](https://developers.tokportal.com/mcp)
- [All agents](https://developers.tokportal.com/agents)