Zebrafish MCP Server

The MCP boundary requires a valid Zebrafish API key, then each tool enforces the scope listed below through the delegated /api/v1 route. A key with only campaigns:write, assets:write, or runs:manage can call its matching least-privilege tools without also granting workflows:read.

Quick Start#

1. Install the Zebrafish skills in the agent workspace:

   BASHCopy

   npx zebrafish-skills install
   npx zebrafish-skills check

   The install adds the router skill, production playbooks, verification script, and optional non-blocking hooks for supported coding-agent workspaces.

2. Create a Zebrafish API key with the narrowest scope set for the job. For agent-assisted OAuth/sign-in, open: https://zebrafish.dev/agent-onboarding?preset=authoring-agent

   • Run only: runs:trigger

   • Read/debug runs: workflows:read or runs:trigger

   • Author drafts: workflows:read, workflows:write, runs:trigger

   • Publish: add workflows:publish

   • Project files: campaigns:read, campaigns:write, assets:read, assets:write

   • Studio: models:read, studio:read, studio:write

3. If the agent will run paid workflows or Studio generations, continue from the key modal to Settings -> Spend and buy prepaid credits through Stripe Checkout.

4. Add the server to Claude Code:

   BASHCopy

   claude mcp add zebrafish https://zebrafish.dev/api/mcp --header "Authorization: Bearer $ADFISH_API_KEY"

5. For Codex, add the same remote MCP server to ~/.codex/config.toml:

   TOMLCopy

   [mcp_servers.zebrafish]
   url = "https://zebrafish.dev/api/mcp"
   
   [mcp_servers.zebrafish.http_headers]
   Authorization = "Bearer adf_..."

6. For another MCP client, configure a remote Streamable HTTP server at https://zebrafish.dev/api/mcp with the header Authorization: Bearer <your-key>.

7. In the agent session, ask: Read the Zebrafish agent playbook, then list my workflows

   Expected output:

   TEXTCopy

   Playbook loaded: discovery loop, safety rules, approval boundaries, and verification steps.
   Blog Post Illustrations (wf_blog_post_illustrations)
   Weekly Launch Recap (wf_weekly_launch_recap)
   Paid Social Variants (wf_paid_social_variants)

8. Ask: Run my Blog Post Illustrations workflow

   Expected output:

   JSONCopy

   {
     "id": "run_01JZ8A1M8QF7YH6K4R5S2T9V0B",
     "workflowId": "wf_blog_post_illustrations",
     "status": "queued"
   }

Main Agent Modes#

Agents interact with Zebrafish in four main modes:

• Direct hosted MCP: Claude Code, Codex, or another external MCP client calls https://zebrafish.dev/api/mcp with a scoped API key. This is the best path for coding agents and operator agents outside the web app.

• In-app /agent tools: Zebrafish's own agent exposes the same MCP-backed capabilities as prefixed tools such as zebrafish_list_workflows and zebrafish_upload_campaign_asset_from_url. Unsafe write/spend/cancel tools go through the app's approval UX. This is the in-app conversational path for workflow authoring: brief the agent, approve draft, test-run, and publish actions, then inspect the resulting runs.

• Public REST /api/v1: CI systems and custom integrations call REST directly with Authorization and Idempotency-Key headers.

• Human UI: Users inspect workflows and runs, manage projects, files, Studio, approvals, settings, and billing in the app. /workflows is the observability surface for workflow definitions, statuses, costs, approvals, outputs, and failures. MCP covers the agent-safe public operations, not every private UI action.

Product note: the human UI calls these workspaces Projects. The public API, MCP tools, scopes, and IDs still use campaign/campaigns names for compatibility until /projects aliases are introduced.

Recommended Agent Workflow#

For reliable autonomous work, keep the same loop for every task:

1. Prime: call get_agent_playbook for non-trivial tasks.

2. Discover: list_workflows, list_campaigns, list_models, or the relevant list/get tool.

3. Inspect: get_workflow, get_workflow_context, get_campaign_knowledge, list_campaign_assets, get_run_trace, or get_run_events.

4. Plan: choose the narrowest write tool and ask the user/client for approval before spend, publish, cancel, approval responses, or asset/campaign writes.

5. Act: call the write tool. MCP clients may omit idempotencyKey; Zebrafish derives one for the tool call. Provide a stable key only when intentionally retrying the same operation. Exception: purchase_credits requires an explicit idempotencyKey (it spends real money). Payment tools are advertised only when AGENT_PAYMENTS_ENABLED is on; rail availability still depends on the fake webhook secret or Stripe Checkout unit price + webhook configuration described in the API key docs.

6. Verify: poll get_run, get_run_events, or get_studio_generation until a terminal state, then use debug/cost/asset URL tools as needed.

Coverage Boundaries#

MCP exposes every major agent-safe product capability: hosted skill discovery, workflow run lifecycle, draft authoring, project reads/writes, workflow-project attachment, file upload/readback, run cancellation, approval responses, redacted traces/events, per-run costs, Studio generation polling, model catalog reads, and org model registration.

It intentionally does not expose account creation, sign-in, API key creation, billing/payment settings, organization membership, admin spend-cap changes, private dashboard configuration, or raw Trigger/FAL/R2 credentials. Those stay in the human UI or protected internal services.

Good Starting Prompts#

Use prompts that name the goal and the allowed scope:

• Read the Zebrafish agent playbook, list my workflows, inspect the one named Blog Post Illustrations, run it with sample-safe inputs, then poll until it finishes.

• Create a project named Spring Launch, attach it to workflow wf_1, upload this public brief URL as a project file, and verify the file is listed.

• Inspect workflow wf_1, read the authoring guide, propose a draft change, validate it, save a draft revision, run a draft test, and stop before publishing.

• List available Studio models, pick the cheapest model that can generate an image, create one generation for this prompt, and poll until terminal. Ask before spending.

• Find run run_1, stream events until terminal, then summarize trace errors and cost breakdown.

Available Tools#

Experimental Authoring Proof Path#

The authoring lifecycle targets an existing workflow or a starter created from image_prompt_starter. Campaign mutation, asset upload/finalize, approval/cancel, and redacted trace reads are now separate tools with narrower scopes.

1. Call create_workflow_from_template if you need a new starter workflow.

2. Call get_workflow_context and copy revisions.latest.id.

3. Call get_agent_authoring_guide.

4. Edit the workflow inputs and steps.

5. Call validate_workflow_definition until ok is true.

6. Call save_draft_revision with basedOnRevisionId.

7. Call test_run_draft.

8. Call get_run_detail_errors to debug redacted failures.

9. Call publish_workflow_revision with revisionId and expectedLatestRevisionId both set to the current latest revision id.

Every authoring error includes top-level docsUrl; when the server can provide it, details includes machine-readable code, cause, fix, retryable, and correlationId.

The same proof path is exposed as public REST endpoints under /api/v1:

upload_campaign_asset_from_url is an MCP convenience tool built on top of the REST presign/finalize pair; there is no separate public REST endpoint for URL fetch uploads.

MCP clients may omit idempotencyKey for mutating tools. Zebrafish derives a trusted key from the MCP request/tool/payload and forwards it to the internal REST handler. Provide a stable idempotencyKey only when you are deliberately retrying the same operation across a client reconnect or a new session.

Exception: purchase_credits REQUIRES an explicit idempotencyKey. A derived key cannot distinguish an agent-level retry from a new purchase, and every new key spends real money — reuse the same key when retrying the same purchase.

REST clients must still send the Idempotency-Key header on create-from-template, draft save, draft test-run, publish, campaign writes, asset upload/finalize, cancel, approval, and Studio generation requests. Reuse a key only for retries of the same payload; reusing it with a different payload returns 409 idempotency_conflict.

create_campaign_asset_upload is the exception to the normal 48-hour replay window: presigned PUT URLs expire after 15 minutes, so upload-creation idempotency is capped below that expiry instead of replaying stale upload URLs.

Asset Uploads#

Use upload_campaign_asset_from_url by default when an agent can point to a public source file. It fetches the source, validates size/MIME/magic bytes, creates the presigned upload, PUTs the bytes, finalizes the asset, and returns the asset IDs in one call.

Source URL requirements:

• HTTPS only

• Publicly routable host; localhost, private IPs, .local, and .internal hosts are rejected

• No redirects; pass the final direct URL

• Allowed MIME: image PNG/JPEG/WebP/GIF, PDF, PPTX, plain text, or markdown

• Size at or below the project file limit

Use create_campaign_asset_upload plus finalize_campaign_asset_upload only when the agent has local bytes that are not already available through a public HTTPS URL. In that flow the agent must PUT bytes to the returned presigned URL before finalizing.

Hosted design_workflow Decision#

No hosted design_workflow LLM tool is exposed in this slice. External agents get the same public-safe authoring guide, campaign context, assets, validation, draft save/test, publish, and trace operations, but they spend their own model budget. Revisit a hosted design tool only with an explicit product decision for app-managed LLM spend, billing, rate limits, and prompt/version ownership.

Failure Modes#

MCP clients display tool failures as isError: true results. The text content is the v1 API error object, preserved with type, message, requestId, docsUrl, and any details.

Missing key, 401:

{
  "isError": true,
  "_meta": { "status": 401 },
  "content": [
    {
      "type": "text",
      "text": "{\n  \"type\": \"authentication_error\",\n  \"message\": \"Invalid or unauthorized credentials.\",\n  \"requestId\": \"req_01HV8XYZABC\",\n  \"docsUrl\": \"https://zebrafish.dev/docs/api-keys#auth-errors\"\n}"
    }
  ]
}

Insufficient scope, 403:

{
  "isError": true,
  "_meta": { "status": 403 },
  "content": [
    {
      "type": "text",
      "text": "{\n  \"type\": \"insufficient_scope\",\n  \"message\": \"This API key does not have the required scope: runs:trigger.\",\n  \"requestId\": \"req_01HV8XYZABC\",\n  \"docsUrl\": \"https://zebrafish.dev/docs/api-keys#scopes\"\n}"
    }
  ]
}

Workflow not found, 404:

{
  "isError": true,
  "_meta": { "status": 404 },
  "content": [
    {
      "type": "text",
      "text": "{\n  \"type\": \"not_found\",\n  \"message\": \"Workflow not found\",\n  \"requestId\": \"req_01HV8XYZABC\",\n  \"docsUrl\": \"https://zebrafish.dev/docs/api-keys#not-found\"\n}"
    }
  ]
}

Spend cap exceeded, 402:

{
  "isError": true,
  "_meta": { "status": 402 },
  "content": [
    {
      "type": "text",
      "text": "{\n  \"type\": \"spend_cap_exceeded\",\n  \"message\": \"This run would exceed your organization's monthly spend cap.\",\n  \"requestId\": \"req_01HV8XYZABC\",\n  \"docsUrl\": \"https://zebrafish.dev/docs/api-keys#spend-cap\",\n  \"details\": {\n    \"currentUsdMicros\": \"6500000\",\n    \"reservedUsdMicros\": \"0\",\n    \"capUsdMicros\": \"7000000\",\n    \"estimateUsdMicros\": \"1000000\",\n    \"projectedUsdMicros\": \"7500000\"\n  }\n}"
    }
  ]
}

Insufficient prepaid usage balance, 402:

{
  "isError": true,
  "_meta": { "status": 402 },
  "content": [
    {
      "type": "text",
      "text": "{\n  \"type\": \"insufficient_credits\",\n  \"message\": \"Insufficient prepaid usage balance.\",\n  \"requestId\": \"req_01HV8XYZABC\",\n  \"docsUrl\": \"https://zebrafish.dev/docs/api-keys#prepaid-usage-balance\",\n  \"details\": {\n    \"requiredUsdMicros\": \"1250000\",\n    \"availableUsdMicros\": \"500000\"\n  }\n}"
    }
  ]
}

Rate limit, 429:

{
  "isError": true,
  "_meta": { "status": 429 },
  "content": [
    {
      "type": "text",
      "text": "{\n  \"type\": \"rate_limit_exceeded\",\n  \"message\": \"API key rate limit exceeded. Retry after the server-provided cooldown.\",\n  \"requestId\": \"req_01HV8XYZABC\",\n  \"docsUrl\": \"https://zebrafish.dev/docs/api-keys#rate-limits\"\n}"
    }
  ]
}

Schema Reference#

The canonical schema reference is the v1 OpenAPI document at /api/v1/openapi.json. MCP tool input schemas are tested against the corresponding v1 operations so schema drift fails CI.