API and MCP setup

1. Set up an app

1. 1. Sign in and create or choose an app.
2. 2. In Claude, open Settings → Connectors → Add custom connector.
3. 3. Name it DistributionOS and use https://distributionos.dev/api/mcp. Leave the optional OAuth Client ID and OAuth Client Secret blank.
4. 4. Choose Connect, sign in to DistributionOS, choose a default app, and approve one connection for your active subscribed apps.
5. 5. In Claude Code, use /mcp to confirm the account connector is available, then verify the connection.
6. 6. Other MCP clients can connect directly to the same endpoint. If OAuth is unavailable, use a write-scoped Account API key as a fallback.

Outcome reports and agent feedback

Call get_outcome_reports for one aggregate evidence bundle spanning goals, funnels, trusted revenue, SEO, and AI visibility. generate_outcome_report compares the latest seven-day window with the preceding one and may create at most one review-required Pipeline proposal when both the sample and materiality thresholds are met. It never approves or executes the task.

After approved work ships, complete_agent_work creates a post-shipment observation window. DistributionOS waits for that window, the configured minimum sample, and the materiality threshold before adding a verified result to durable agent context. Reports contain aggregates only, and observed changes are associations unless a controlled experiment supports a causal claim.

Call get_outcome_context_timeline to line up source-linked X/Reddit owned-brand watchlist signals, verified shipped-work receipts, optional GitHub annotations, and aggregate measurement results. Broad niche research is excluded. Use add_github_outcome_annotationonly for a specific commit or release URL; the annotation adds context and never turns commit count or timeline proximity into an impact claim.

On apps enabled for the benchmark rollout, prepare_ai_visibility_action_packet accepts one repeated prompt gap from an unchanged comparable series. It preserves the exact sample lineage, cited-source shape summary, competitor evidence, claim boundaries, and two/four-week rerun dates in one review-required Marketing Pipeline item. The tool cannot approve, publish, schedule, or execute the proposed work.

2. Codex setup

Open the app's Settings → Agent connections page for the app-specific repo prompt. Codex uses one DistributionOS server across your repositories. Skip the add command when it is already registered, but always run login to create or refresh the account authorization.

codex mcp add distributionos --url https://distributionos.dev/api/mcp
codex mcp login distributionos

During browser approval, choose the current repository's app as the default. Do not add a differently named server for each app: clients can expose identical tool names through one shared namespace. After login, fully restart Codex and open a fresh task from the app repository.

3. Claude connector setup

Claude account connectors are the recommended path for Claude and Claude Code. DistributionOS supports Dynamic Client Registration, so customers should not enter a Client ID or Client Secret. App selection happens on the DistributionOS approval screen.

A connector added to Claude is automatically available in Claude Code when Claude Code is signed in through the same Claude.ai subscription. If Claude Code uses an API key, Bedrock, Vertex, or another authentication method, add the remote server directly instead.

4. Direct OAuth setup

OAuth-capable MCP clients can connect directly to the remote endpoint and request read/write scopes. One approved connection can address any active app the signed-in user owns, while every app-specific request still checks ownership and paid access. DistributionOS publishes OAuth discovery metadata for this server.

[mcp_servers.distributionos]
url = "https://distributionos.dev/api/mcp"
scopes = ["read", "write"]
oauth_resource = "https://distributionos.dev/api/mcp"

Discovery endpoints: /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. The OAuth flow uses authorization code + PKCE.

5. API key fallback

For clients that cannot complete OAuth yet, create a write-scoped app key and pass it as a bearer header. Store the token outside the repo.

{
  "mcpServers": {
    "distributionos": {
      "type": "http",
      "url": "https://distributionos.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer dos_live_..."
      }
    }
  }
}

Remote MCP, OAuth bearer tokens, and raw API calls are the live beta paths. For clients that only support stdio MCP, a local bridge such as npx distributionos-mcp should be treated as a planned fallback until the bridge package is published or installed locally.

User-configured Codex and Claude Code connections do not need a marketplace listing. Other MCP clients may be protocol-compatible, but they are untested and are not currently supported.

6. Verify the agent connection

Writing project MCP config does not prove the agent can use DistributionOS. After setup, first ask the connected agent to list visible MCP tools:

List the MCP servers/tools you can see. Do not inspect the repo.

If only DistributionOS authentication tools are visible, authenticate and complete OAuth first. Then ask:

Check the DistributionOS connection for this app. Use the DistributionOS MCP tools: call check_distributionos_connection, fetch the latest agent instructions, then tell me today's analytics summary.

A healthy agent should call check_distributionos_connection, get_agent_instructions, andget_analytics_summarywith the repository's exact app ID. The onboarding dashboard waits for a successful app-specific MCP call before treating the agent connection as verified. API keys remain an app-scoped fallback for advanced clients, but API fallback alone does not complete the normal MCP onboarding checkpoint.

7. Initialize DistributionOS once

After MCP/API access is connected, the human prompt can stay short:

Initialize DistributionOS for this repo.

The agent should call get_agent_instructions, propose the managed startup block for approval, write it, and call report_managed_bootstrap_installation with only that exact block and its repo-relative file path. DistributionOS stores a hash receipt, not the instruction file. WhensetupMode is first_setup, the agent then inspects repo/app evidence and callssubmit_initialization_context with sourced claims, unknowns, risks, and next steps. WhensetupMode is additional_agent, it stops after the client-specific receipt and preserves the existing app context. Claude does not need npm for this connector-native setup path. Distribution OS returns a dashboard review URL so the user can approve the generated Brain Doc and Brain Vault draft.

Raw API fallback: POST the same structured payload to /api/v1/apps/<app-id>/onboarding/initialize with a write-scoped bearer key.

Supported clients: Codex and Claude Code

Authority Publishing controlled rollout

DistributionOS is the control plane: it stores the campaign, master topic universe, destination scope, approvals, one-action leases, exact-draft fingerprints, publication reports, public verification receipts, and measurement. The user's Codex or Claude Code agent is the operator: it owns the external schedule, browser or computer-use session, destination sign-in, and approved interaction. DistributionOS does not need a built-in Medium or browser publisher for this workflow.

Campaign tools are visible only for enabled apps. If get_agent_instructions reports authorityPublishing.enabled=true but the Authority Publishing tools are absent, reconnect or restart the client once so it refreshes the MCP tool manifest. Do not work around the connection by copying browser credentials or switching to an unreviewed API key.

1. 1. Read the campaign with get_authority_publishing_campaign.
2. 2. Use get_authority_topic_prompt and propose_authority_topics; stop for topic review.
3. 3. Create only reviewed topic-by-destination targets, then prepare assignments and exact drafts through one claimed action at a time.
4. 4. Use get_authority_worker_setup to generate the one-time setup and recurring-run prompts. This does not create a schedule.
5. 5. Show the user the exact task name, cadence, approval mode, runtime requirements, and capabilities. Create the external task only after explicit approval.
6. 6. Register a sanitized scheduler receipt, pass the no-publish dry run, activate the reviewed wave, and then heartbeat, claim, report, verify, and close exactly one action per run.

Codex automations can run recurring work, but a local automation may depend on the computer being awake and Codex running. Claude Code can use an enabled durable /schedule cloud job; its local /loop is temporary and is not accepted as a durable campaign schedule. Capability and workspace-policy checks remain part of every worker setup.

Available tools

Tool descriptions are written for natural-language agents. In normal use, ask for the outcome you want; the agent should choose the matching Distribution OS tools.

Agent workflow resource

MCP clients can read dos://workflow-guide for recommended tool order, common intent mappings, and safety rules. During first setup, call get_agent_instructions, thenreport_managed_bootstrap_installation after the user approves and the managed block is written, then submit_initialization_context. After review, a good default sequence islist_apps, get_app_context, get_brain_doc, then update_brain_doc when the current Brain Doc needs a repo-grounded overhaul, followed by plan, research, artifact, and analytics tools as needed.

Analytics contract

When first-party analytics is enabled, agents should treat analytics as required by default for public DistributionOS-created or modified assets. Call get_analytics_install_instructions before public blog, landing page, CTA, email, social, launch, paid, or campaign-link work. Install the tracker once in the global public layout, keep canonical URLs clean, tag pages with distributionos:content-id ordata-dos-content-id, and use create_tracked_link for primary CTAs and campaign links. For public subscribe, payment-start, or hosted checkout handoff flows, send checkout_startedbefore the redirect/session handoff when the tracker is available. For public signup, waitlist, and email-capture forms, send signup, waitlist_joined, or email_subscribedonly after the submit succeeds. Browser-side purchase and revenue events are intentionally out of scope. Provider-verified lifecycle and money outcomes use the server-only /api/v1/apps/[appId]/measurement/outcomes contract with an app-scoped API key, exact minor units, idempotent receipts, and verified-only attribution. Agents can inspect the result with get_trusted_revenue_summary but cannot fabricate revenue events.

For apps that bill through Polar, the user can connect the customer app's organization in Analytics > Revenue. Agents should call get_polar_revenue_connection to distinguish not connected, connected but waiting for a verified event, and degraded states. The tool returns a safe dashboard URL and receipt counts; it never returns the organization token, webhook secret, customer identity, or raw provider payload. This connection is separate from the Polar account that bills for DistributionOS.

For apps that bill through Stripe, the user can connect one or more direct or Connect-scoped accounts in Analytics > Revenue. Agents should call get_stripe_revenue_connections to inspect safe test/live health, webhook receipt counts, revoked or degraded credentials, and the latest bounded historical-sync receipt. DistributionOS creates the signed endpoint, encrypts the account-scoped key, and never returns keys, signing secrets, account IDs, customer identity, or raw events. Checkout and invoices are canonical by default; a direct PaymentIntent is counted only when the app explicitly marks it as canonical revenue, preventing one payment from being counted through several Stripe event types.

For Google visibility, call get_google_platform_visibility. It returns ordinary Web search performance, app-root URL Inspection, imported official Google AI-feature impressions, and dated Gemini observations as separate evidence. Google's dedicated Generative AI performance report covers AI Overviews and AI Mode but is still in limited rollout; when no dedicated API is available, users import the reviewed Search Console CSV. Agents must never relabel standard Search Console impressions as Google AI or Gemini impressions.

For apps running Meta ads, the user authorizes read-only access and chooses app-owned accounts and campaigns in Analytics > Paid. Agents call get_meta_ads_attribution to inspect safe aggregate spend, delivery, first-party traffic, trusted linked revenue, match confidence, unmatched data, and sync freshness. First-party ROAS uses only same-currency trusted revenue with approved campaign linkage. Meta-reported purchases and modeled ROAS remain separate and are never relabeled as first-party attribution.

During analytics setup, scan existing public blog posts and landing pages. Backfill page markers where DistributionOS should measure outcomes, or include analyticsOptOutReason inreport_implementation for private, sensitive, legal, billing/account, or platform-restricted pages. After deployment, call verify_analytics_install and report pending or failed tracking honestly.

AI Visibility readiness workflow

run_ai_visibility_readiness starts one queued, bounded multi-page audit and returns a run ID immediately. Poll get_ai_visibility_readiness_run for discovery, crawling, analysis, and final findings. Completed runs report Ready, Needs work, Incomplete, or Failed with transparent core counts instead of a percentage. Useget_ai_visibility_remediation to generate a deterministic coding-agent prompt from the exact immutable run, then rerun the audit after deployment to compare resolved, remaining, and new findings. Optional items such asllms.txt never block Ready. Readiness does not prove mentions, citations, rankings, or referrals.

For server-side crawler observation, call get_ai_crawler_install_instructions for a copy-ready Next.js/Vercel Edge or Node/Express adapter and signed self-test. Then call verify_ai_crawler_install. Adapter delivery, real crawler activity, and official provider IP verification are separate states. A healthy adapter may wait for a real crawler indefinitely. Crawler requests prove only that a public page was fetched; they do not prove an AI answer, citation, impression, recommendation, ranking, or training use.

First proposed plan workflow

1. 1. Ask your agent to call list_apps, then choose the app.
2. 2. Call get_app_context and get_brain_doc.
3. 3. If the Brain Doc is stale, generic, or wrong, inspect grounded repo/site evidence and call update_brain_doc with mode=propose. Use mode=apply only after explicit user approval.
4. 4. Call propose_distribution_plan when the user asks for a plan, strategy, campaign, roadmap, content ideas, keyword priorities, or next steps.
5. 5. Use research_keywords or analyze_serp when SEO data is needed.
6. 6. Before public page, CTA, email, social, or campaign-link work, call get_analytics_install_instructions when analytics is enabled.
7. 7. After approval, call create_artifact for content briefs, landing page copy, social posts, email drafts, or imported/live page artifacts.
8. 8. For hosted images, call get_media_credit_status, then generate_hosted_image for social, landing, launch, blog/page, or video reference assets.
9. 9. Use create_tracked_link for primary CTAs and campaign links.
10. 10. After publishing externally, call verify_analytics_install, then report_implementation with the published URL.

Plans, credits, and disabled hosted generation

DistributionOS is $50/month or $500/year per subscribed app. Both billing options include every available feature, unlimited tasks and handoffs, 50 media credits, 5 connected social profiles, 50 fresh research runs, and 250 AI visibility checks per month. One AI visibility check tests one monitored buyer question with one supported provider. All supported provider families are included. Hosted article generation is disabled; your agent writes, edits, publishes, and reports the shipped URL. DistributionOS-hosted images can be generated through generate_hosted_image; app monthly media credits are spent before account-shared top-up credits.

The server records provider cost events, tracks API key usage, caches repeated expensive calls, and can force cache-only or paused provider states if an agent loop or abnormal usage pattern appears.