Architecture & implementation

This guide describes the implementation in this repository. It does not mean the feature has been deployed or enabled on the live domains. Read the main guide for client setup and deployment instructions before enabling it.

Application architecture found in the audit

Older controllers and migration-era provider code still exist in the repository. The MCP integration uses the native services. In particular, it does not publish through the older PublishScheduledPostJob, which has legacy billing behavior.

Protocol and request flow

The remote endpoint runs inside Laravel using laravel/mcp 1.0.1, the official Laravel MCP package. Protocol transport, JSON-RPC messages, initialization, version negotiation and tool discovery come from that package. Caroush does not implement a look-alike REST replacement for MCP.

flowchart TD
    Agent[MCP client] --> Endpoint[Laravel MCP HTTP endpoint]
    Endpoint --> Auth[Passport token and workspace grant checks]
    Auth --> Tools[Tool catalog, schemas and scopes]
    Tools --> Read[Immediate read]
    Tools --> Operation[Durable mutation operation]
    Operation --> Approval[Browser approval when required]
    Approval --> Queue[Existing database queue]
    Operation --> Queue
    Read --> Domain[Shared Caroush services]
    Queue --> Domain
    Domain --> Data[PostgreSQL, filesystem and existing providers]

The principal components are:

Authentication and workspace isolation

OAuth uses Passport 13.7.6 and League OAuth2 Server 9.4.1. Supported grants are authorization code with PKCE S256 and refresh token. The current public-client registration flow uses token_endpoint_auth_method=none; it does not issue a shared Caroush API key or a client secret for desktop agents.

1. The client reads protected-resource metadata and authorization-server metadata.
2. It registers callback URLs when dynamic registration is enabled. HTTPS and localhost redirects use exact matching; numeric HTTP loopback redirects allow variable ports under RFC 8252. Code exchange still requires the exact redirect used during authorization.
3. It sends the advertised resource URL, requested scopes and a PKCE challenge to the authorization endpoint.
4. The user signs into the existing Caroush browser session, chooses a workspace and approves scopes.
5. The client exchanges the authorization code with the PKCE verifier and matching resource URL.
6. Subsequent MCP calls use the access token in the Authorization header.

Access tokens last one hour. Refresh tokens last 30 days and rotate after use. Workspace grants retain the user, registered client, approved scopes and exact resource URL. Revocation invalidates the grant and its associated access tokens, refresh tokens and unused authorization codes.

Account::useWorkspace() pins request-local service context. It does not alter users.current_workspace_id, so changing the browser workspace cannot silently move an MCP connection. Membership is rechecked, including when an approved background action starts. Nested records are authorized through their parent post or carousel run. MCP-owned data checks constrain both creator and workspace, including when another user's record is located in the same workspace.

Raw social-account models are never public results: their encrypted casts decrypt credentials when accessed, so serialization requires an explicit allowlist. Tool outputs omit social tokens, refresh tokens, internal provider configuration, claim tokens, raw generation snapshots and storage descriptors.

Shared services rather than duplicate implementations

The integration extracts existing controller behavior into these application services:

• PostContent: existing content creation and deletion behavior.
• CarouselContent: existing carousel creation/review operations.
• PostScheduling: composer validation, destination checks, approval checks, TikTok consent validation, duplicate prevention and native publication orchestration.
• AutomationManagement: list/run history plus lifecycle actions shared with the browser. Pausing remains possible when a product or account disappears. Deleting an automation cancels unfinished work and preserves existing publication safeguards and refunds.
• SocialOperations: owner-scoped connected-account and delivery DTOs.
• StoredMediaUpload: converts an owned stored media asset into a bounded temporary upload for existing CTA validators; it accepts an asset ID, never a local path or arbitrary remote URL.

Video/carousel automation saves still use their original AutomationService::save() methods. Native run requests still use Scheduler::runNow() and the same UUID occurrence ledger as the web application. Existing browser controller responses are preserved by thin service delegates.

Operations, idempotency and approval

Every mutating tool requires a UUID idempotency_key. The operation ledger is unique for authorization, tool name and key. Repeating the same request returns its existing operation; reusing the key with different arguments returns idempotency_conflict.

Publishing, scheduling, automation activation/changes/runs and deletion require approval through the authenticated Caroush browser. A tool call initially returns approval_required with an approval_url. The browser reviews the stored request; the agent cannot manufacture approval by adding approved=true or inserting instructions into content. Approval requests expire after 30 minutes by default.

Approval permits only that stored action. The queue rechecks the grant, membership and required scope before execution. If permission was revoked while work waited, the action fails without receiving new authority from the old approval.

MCP operation IDs and native automation run IDs have different meanings:

A successful queued request is not evidence that the resulting content exists or was published. A completed run_automation MCP request can mean its native run was accepted; continue polling the returned native run. Delivery status and confirmed platform receipts determine publication success.

If an unexpected worker failure could have happened after an external effect, the operation is marked outcome_unknown. Do not generate a fresh key and blindly retry it. Inspect Caroush and the destination platform first.

Actual social and automation capabilities

Existing publisher implementations cover Instagram, TikTok, Facebook, LinkedIn, X/Twitter, Threads and Bluesky. Platform permissions, media constraints and publication approval requirements still apply. Current image limits are Instagram 10, TikTok 35, Facebook 10, LinkedIn 20, Threads 20, X 4 and Bluesky 4; the app rejects oversized carousels instead of dropping slides.

Direct TikTok submission through generic MCP publish_post or schedule_post is intentionally rejected. The user must view that post in the Caroush composer and complete creator-specific privacy, media-preview and consent controls. Automation definitions may target TikTok, but the existing pipeline holds the completed TikTok output for per-post review.

Generation automations support:

New MCP definitions are drafts. Enabling and running are separate approval-required actions. Prices come from existing runtime credit configuration: at current defaults, generated images are 5 credits each, 2×2 is 20 credits, single fade is 5 credits, and UGC automation is 10 credits. Uploaded carousel CTA artwork replaces one generated slide and reduces the generated-image charge. The credit ledger performs reservation, capture and refunds; clients cannot submit a price.

Legacy posting folders support weekly slots for existing approved drafts. They are distinct from the daily generation automation tool family. No first-class campaign model, arbitrary trigger graph, RSS/event-triggered generation or optimal posting-time predictor was found; do not describe these as available MCP tools. A folder named “Campaign” is not a campaign API.

Analytics semantics

MCP analytics read saved real snapshots and observations for posts actually delivered through Caroush. Reads do not fetch an account feed or contact providers. The existing Pro analytics entitlement applies.

The daily sync runs at 00:00 America/New_York by default. This timezone changes with New York daylight-saving time. The configured application scheduler dispatches individual jobs to the existing database queue. Each scheduled daily sync has a unique post/source/date ledger entry.

Reported metrics depend on platform and granted permissions:

A missing metric stays unavailable, not zero. Publication-date filtering selects a cohort of posts; headline metrics are lifetime totals at their last sync. activityTrend reports observed changes between consecutive stored observations and exposes coverage. Summing post reach does not produce unique people across posts. get_best_performing_content ranks up to five posts only where a views metric exists, preserving platform differences.

Persistence and operational boundaries

Two additive migrations create the required Passport/workspace authorization tables and MCP operation/audit tables. Application content, credit and publishing tables remain authoritative. Operation arguments and results use encrypted casts; preserve the existing APP_KEY. Browser consent nonces are hashed. Access/refresh-token persistence follows Passport/League formats; clients never receive database or platform secrets.

The SDK endpoint uses normal PHP-FPM. No additional MCP daemon, sidecar or container is required. MCP background work uses the database connection and caroush queue with the existing 1800-second worker. Video/carousel native runs then execute on their existing dedicated queues.

Audit events record user/workspace/grant/request/operation identifiers, tool name, result status, timing, error code and argument names. They do not record prompts, captions, uploaded contents, tokens or raw provider errors. Existing error reporting routes unexpected failures to Sentry. This does not add a second product-analytics SDK.

Implementation file inventory

Paths below are relative to the Laravel repository. The complete tool inventory and exact schemas are generated into catalog.json and tools.md in the documentation download.

Created

Modified

Private .env and .env.production files were not changed. The populated application database and production configuration were not migrated or modified during implementation; automated migration checks ran against isolated test databases.