# Aivy Marketing > MCP tools for an external assistant to read a brand, draft posts, attach media, and schedule or publish to connected social channels. Aivy is an AI marketing agent for small businesses and creators. It learns a brand from its website (Brand DNA), builds a marketing strategy and a 12-month content plan, writes posts, schedules and publishes them to connected social channels (LinkedIn, Facebook, Instagram, X), and reports results. There is a Free plan; paid plans are Solo, Growth and Scale (https://aivymarketing.com/#pricing). AI assistants are welcome: connect through the MCP endpoint below. ## Canonical URLs - Website: https://aivymarketing.com - Developer docs: https://aivymarketing.com/developers - All agent docs in one file: https://aivymarketing.com/llms-full.txt - MCP endpoint: https://aivymarketing.com/api/mcp - Protected resource metadata: https://aivymarketing.com/.well-known/oauth-protected-resource/api/mcp - Authorization server metadata: https://aivymarketing.com/.well-known/oauth-authorization-server - Tool reference: https://aivymarketing.com/api/agent/openapi.json - Setup guide for people: https://aivymarketing.com/docs/ai-assistants.md - Walkthrough: https://aivymarketing.com/docs/agent-mcp.md ## Authentication OAuth 2.1 clients (dynamic client registration, PKCE S256) are sent to https://aivymarketing.com/connect/agent, where the person signs in or creates an account and approves. Aivy is the authorization server. The access token is an opaque aivy_at_ grant, not a Supabase JWT. Clients without OAuth use a key the person creates under Settings → AI Assistants (https://aivymarketing.com/ai-assistants). It starts with aivy_at_, is shown once, and is sent as Authorization: Bearer aivy_at_... A grant can cover chosen brands or all of the person's brands, including brands created later. Scopes aivy.reader, aivy.drafter, and aivy.publisher are ceilings. Consent can choose a lower profile. ## Profiles - Reader: brand, strategy, channels, posts, media, and analytics. - Drafter: reader plus drafts, media uploads, brand and strategy writes, and optional generation inside a ceiling. - Publisher: drafter plus schedule_post and publish_post. A drafter cannot publish or schedule. When requireApproval is on, those tools return pendingApproval until a person approves the post in Aivy. ## Setting up a brand Call get_setup_status and continue with its nextStep: create_brand, start_website_scan (or create_brand_dna_without_website), get_brand_dna and approve_brand_dna, get_strategy_questions and save_strategy_answers, generate_strategy, get_strategy_draft and approve_strategy, create_content_plan and get_content_plan. Scans, strategies and plans build in the background; read them again after checkAgainInSeconds. They cost 9, 5 and 14 credits from the person's Aivy account. The MCP prompt set_up_my_brand starts this flow. ## Workflow Read brand context and channels, create an unpublished draft, attach media, fix validation errors, schedule or publish, then poll get_publish_status. ## Retired REST API https://aivymarketing.com/api/agent/v1 returns HTTP 410. Use the MCP endpoint above. --- Developer docs (HTML): https://aivymarketing.com/developers --- Source: https://aivymarketing.com/docs/ai-assistants.md # Use Aivy from ChatGPT, Claude or Grok Aivy works inside AI assistants. Connect it once, then ask your assistant to set up your brand, plan your content or write and schedule posts. You decide what each assistant may do, and you can disconnect it at any time. **Aivy's address for AI assistants:** `https://aivymarketing.com/api/mcp` ## What you can ask - "Show my Aivy brands and what is planned for next week." - "Write three LinkedIn post drafts about our spring offer." - "Which of my posts did best last month?" - "Schedule the draft about the workshop for Tuesday at 9:00." (only if you allowed scheduling) ## Connecting When you connect, an Aivy window opens. There you: 1. Sign in, or create an Aivy account (we e-mail you a 6-digit code). 2. Choose the brands: all of them (including brands you create later), or only some. 3. Choose what the assistant may do: - **Look only** – reads your brands, strategy, content plan, posts and results. - **Set up my brand and prepare drafts** – also fills in Brand DNA, strategy and content plan, and writes drafts. Nothing is published. - **Also schedule and publish** – can post on your connected social accounts. You can hold every post for your approval in Aivy first. 4. Choose how many credits it may spend on AI work. Setting up a brand uses about 28 credits. 5. Click **Allow and go back**. ### Claude (claude.ai, desktop app, Cowork) 1. Open **Settings → Connectors** and choose **Add custom connector**. 2. Name it **Aivy** and paste `https://aivymarketing.com/api/mcp`. 3. Click **Connect** and approve in the Aivy window. Custom connectors need a paid Claude plan. In a Team or Enterprise workspace, an owner may need to add Aivy first. ### Claude Code ``` claude mcp add --transport http aivy https://aivymarketing.com/api/mcp ``` Then type `/mcp` in Claude Code, choose **aivy** and sign in. ### ChatGPT Until Aivy is listed in the ChatGPT app directory: 1. Open **Settings → Apps & Connectors → Advanced settings** and turn on **Developer mode**. 2. Choose **Create**, name it **Aivy**, paste `https://aivymarketing.com/api/mcp` and pick **OAuth**. 3. Approve in the Aivy window, then turn Aivy on from the tools menu in a chat. ### Grok (grok.com) 1. Open **grok.com/connectors** and choose **New Connector → Custom**. 2. Paste `https://aivymarketing.com/api/mcp` and sign in to Aivy. ### Grok Bot, Cursor and other MCP clients Clients that sign in by themselves only need the address. For clients that need a fixed key: 1. In Aivy, open **Settings → AI Assistants** and choose **Create a key**. Copy the key; it is shown once. 2. Add the address and this header in your client: `Authorization: Bearer `. Keys work for 90 days. You can replace or disconnect them under **Settings → AI Assistants**. ## Managing assistants **Settings → AI Assistants** in Aivy shows every connected assistant, what it may do, the credits it used and what it did. **Disconnect** stops it right away. ## Privacy and safety - An assistant sees only the brands and actions you allowed. - Nothing is published unless you chose **Also schedule and publish**; with approval on, every post waits for you in Aivy. - Aivy never shows your social account passwords or tokens to an assistant. - The assistant's provider (for example OpenAI or Anthropic) receives the Aivy data it reads in your chat. See our [Privacy policy](https://aivymarketing.com/privacy). Questions: write to us from **Help** in the Aivy app. --- Source: https://aivymarketing.com/docs/agent-mcp.md # Aivy agent MCP The agent endpoint is `https://aivymarketing.com/api/mcp`. Create a publisher key at `/connect/agent` and confirm that the key may schedule and publish. This example uses a grant with requireApproval turned off. ## Create a LinkedIn post, attach an image, and schedule it 1. `get_brand_context` with the brand id. 2. `list_channels` and confirm LinkedIn `canPublishNow` is true. 3. `upload_media` with `filename`, `mimeType`, and an `idempotencyKey`. Upload the image bytes to the returned URL. 4. `create_post_draft` with one LinkedIn variant, the caption, and `mediaIds` from the upload. The post stays unpublished. 5. `schedule_post` with `scheduledAt` of `2026-10-22T09:00:00` and the brand timezone `Europe/Prague`. A timestamp without an offset uses the brand timezone, so this is 09:00 in Prague (07:00 UTC while Prague is on summer time). 6. `get_publish_status` returns `scheduled`, the provider post id, and a permalink when the network has one. 7. After the post is live, `get_post_metrics` returns impressions, reach, engagement, clicks, and the permalink. Fields the provider has not sent are null. ```json { "name": "schedule_post", "arguments": { "brandId": "BRAND_ID", "postId": "POST_ID", "scheduledAt": "2026-10-22T09:00:00", "idempotencyKey": "linkedin-prague-2026-10-22" } } ``` A successful direct schedule looks like: ```json { "ok": true, "data": { "status": "scheduled", "providerPostId": "PROVIDER_POST_ID", "permalink": null, "scheduledAt": "2026-10-22T07:00:00.000Z", "scheduledAtLocal": "2026-10-22T09:00:00", "timeZone": "Europe/Prague" } } ``` ## Approval When the same publisher grant has requireApproval on, `schedule_post` and `publish_post` do not send the post. `get_publish_status` returns `pendingApproval` until a person approves it in Aivy. After approval, the existing scheduler sends it. A drafter key cannot call `schedule_post` or `publish_post`. --- ## Tool reference (47 tools; minimum profile in brackets) ### Account and usage - get_account [reader]: Read the signed-in account and the active Aivy grant. Does not include secrets. - list_brands [reader]: List brands this grant may read. - get_usage [reader]: Read credit balance and billing mode. This does not spend credits. ### Brand setup - get_setup_status [reader]: Read how far a brand is through Aivy setup (Brand DNA, strategy, 12-month content plan), which step comes next as nextStep, running background jobs, and a link to the matching Aivy page. Without brandId it lists the brands, or returns step create_brand when there are none. - create_brand [drafter]: Create a brand in the Aivy account with a name and an optional website. Returns the brand id. Spends no credits. - start_website_scan [drafter]: Start reading the brand website to propose its Brand DNA (logo, colors, fonts, tone, audience). Costs 9 credits from the Aivy account, counted against this connection's credit limit. Runs in the background for a few minutes; get_website_scan reads progress. An already running scan is returned instead of starting a second one. - get_website_scan [reader]: Read the status of a website scan (queued, running stages, awaiting_review, failed) and, once finished, the proposed Brand DNA. - get_brand_dna [reader]: Read the current Brand DNA (name, industry, tagline, value proposition, audience, tone, personality, key messages, colors, fonts, language, country, time zone) and whether it is proposed or approved. - update_brand_dna [drafter]: Change Brand DNA fields. Only the fields sent change. Does not approve it. - approve_brand_dna [drafter]: Mark the current Brand DNA as approved. The strategy and content plan are built from the approved version. - create_brand_dna_without_website [drafter]: Create an empty Brand DNA for a brand that has no website, to be filled with update_brand_dna. Returns the existing one when there already is one. Spends no credits. - get_brand_context [reader]: Read brand voice, identity, do and dont words, language, timezone, and visual guidelines. ### Strategy - get_strategy_questions [reader]: Read the strategy questions in five chapters (business, customers, brand, growth, future) with their answer keys, kinds, allowed options, which are required, and the answers saved so far, including answers prefilled from the website scan. missingRequired lists the keys still needed. - save_strategy_answers [drafter]: Save answers to strategy questions by answer key. Select answers must use the listed option text exactly; multi-select answers are lists. Starts the questionnaire if needed. Returns missingRequired. - generate_strategy [drafter]: Build the marketing strategy from the saved answers and the approved Brand DNA. Costs 5 credits from the Aivy account, counted against this connection's credit limit. Runs in the background; get_strategy_draft reads the result. Requires every required question to be answered. - get_strategy_draft [reader]: Read the latest marketing strategy (goals, audience, positioning, offer, messages, content pillars, channels and cadence), whether it is still being built, and whether it is approved. - edit_strategy [drafter]: Change one field of the latest strategy, e.g. keyMessage or primaryGoal (editableFields in get_strategy_draft). An edited strategy needs approval again. - approve_strategy [drafter]: Approve the latest strategy. The 12-month content plan can only be built from an approved strategy. - get_strategy [reader]: Read strategy goals, audience, positioning, content pillars with ids, and the roadmap summary (id, status, startDate, endDate). Week items are on get_pipeline_week. roadmap is null when this brand has no roadmap. ### Content plan - create_content_plan [drafter]: Build the 12-month content plan from the approved strategy. Costs 14 credits from the Aivy account, counted against this connection's credit limit. Runs in the background; get_content_plan reads the result. - get_content_plan [reader]: Read the 12-month content plan: start date, which months are ready, and the items of one month (week, type, platform, title). Also says whether it is still being built. - edit_content_plan_week [drafter]: Change the plan of one week: title, weekTheme, weeklyStory, weeklyGoal, mainMessage or stage (awareness, consideration, decision or retention). A week whose master content is already written cannot be changed here. - get_pipeline_week [reader]: Read one content-plan week for a granted brand. - get_content_item [reader]: Read one post or roadmap item in a granted brand. A post includes body, hashtags, mediaIds, media, accountKind, scheduledAt, publishedAt, permalink, providerPostId, version, and updatedAt. ### Channels - list_channels [reader]: List channel health, account name, handle, page or profile type, token expiry, and whether the channel can publish. Tokens are not returned. - get_channel_connect_url [drafter]: Return a link a person opens to connect or reconnect a channel, including Instagram. Tokens are not returned. ### Posts - list_calendar [reader]: List posts in an explicit interval. A timestamp without an offset uses the brand timezone. - list_posts [reader]: List posts for one brand with optional status, platform, and cursor. - create_post_draft [drafter]: Save 1 to 5 unpublished posts. Validates platform limits before saving. Does not publish. scheduledAt is stored only. - update_post_draft [drafter]: Update text, hashtags, placement, format, media, or scheduledAt on an unpublished post. - duplicate_post [drafter]: Copy an unpublished or published post onto another platform as a new ready draft after validation. - delete_post [drafter]: Delete an unpublished, unscheduled post. A scheduled post must be unscheduled first. A published post deletes the PostForMe record when that call succeeds. networkRemoval is unconfirmed because this does not prove the native network post was removed. - archive_post [drafter]: Archive an unpublished, unscheduled post. The scheduler ignores archived posts. ### Publishing - schedule_post [publisher]: Schedule a post at least 5 minutes ahead. Requires posts.publish and allowPublish. With requireApproval, the post waits for a person in Aivy. The stored time is the scheduled_at echoed by PostForMe. dryRun returns that provider payload and does not send it. - unschedule_post [publisher]: Cancel a scheduled provider post. If the provider cancel fails, the local post stays scheduled. - publish_post [publisher]: Publish a post now. Requires posts.publish and allowPublish. With requireApproval, the post waits for a person in Aivy. - get_publish_status [reader]: Read scheduled, publishing, published, failed, or pendingApproval plus the provider id, permalink, and publishedAt. changedFields is empty unless this read synced a provider change. A published post has publishedAt and scheduledAt null. ### Media - upload_media [drafter]: Create a media id and a signed upload URL for an image or video. The secret is not a provider token. - upload_media_from_url [drafter]: Import a public https image or video into the brand library. - list_media [reader]: List media for a granted brand. - get_media [reader]: Read one media file, including alt text and dimensions. - delete_media [drafter]: Delete media that is not used by a scheduled or published post. ### AI generation - estimate_generation [reader]: Estimate generation cost in dc. This does not spend credits. - generate_post_variants [drafter]: Generate post text inside the grant generation ceiling. - generate_image [drafter]: Generate an image inside the grant generation ceiling and store it as media. ### Analytics - get_post_metrics [reader]: Read impressions, reach, engagement, clicks, and permalink for one post from the provider feed. Missing numbers are null. availability is not_available_yet with a reason when the provider has no metrics. - get_brand_metrics [reader]: Read impressions, reach, engagement, clicks, and followers delta for a brand interval. start and end are required ISO timestamps. A value without an offset uses the brand timezone. When no feed row contributes, availability is not_available_yet and the numbers are null.