Get started

Quick start

Your first connection, from authorization to a successful tool call.

Take the docs with youMarkdown for your editor or agent.
Download guide

Caroush MCP lets an authorized AI agent use the same Laravel services that power Caroush: products, content, carousels, captions, scheduling, publishing, generation automations and saved analytics. Each connection is bound to one user and one workspace. This guide documents the implemented API, not a list of planned endpoints.

The intended production resource is https://mcp.caroush.com/mcp, with https://app.caroush.com as the OAuth issuer. These addresses are configurable. Local installations should use the endpoint shown in Settings → AI connections. The public documentation route is /developers/mcp; a separate docs hostname can serve it at /.

Protocol: Laravel MCP 1.0.1, Streamable HTTP, JSON-RPC 2.0. The SDK supports MCP 2026-07-28 and legacy initialization versions including 2025-11-25 and 2025-06-18. It supports request-scoped streaming, not a permanent server event stream. GET and DELETE on /mcp return 405. There is no conventional /api/generate_carousel REST endpoint: invoke named tools through tools/call.

Status: implemented and tested locally; this change does not deploy the service, provision DNS, or validate production provider credentials. Real AI/provider calls require your configured account, permissions, credits and running workers. Test fixtures mock provider calls to avoid charging credits or publishing content during verification.

Your first connection

  1. An operator enables MCP, runs the additive migrations and configures persistent Passport signing keys. See mcp-deployment.md in the documentation download.
  2. Add the remote endpoint in an MCP client supporting OAuth authorization code + PKCE and public client registration.
  3. The client opens Caroush. Sign in, select one workspace and approve only the permissions needed.
  4. Discover available tools. Call get_profile, get_workspace and get_credit_balance to confirm the context.
  5. Read schemas before invoking tools. Mutations require a UUID idempotency_key.
  6. Follow approval_url when returned. Queued requests and native generation runs must be polled for their actual outcome.

No shared Caroush API key is used. An agent never receives database, Stripe, AI provider or social-network credentials.