Connect your AI assistant to Aivy

Connect in one minute

Add https://aivymarketing.com/api/mcp as a remote MCP server (Streamable HTTP). An Aivy window opens where the person signs in or creates a free account, picks the brands, and chooses what the assistant may do.

claude mcp add --transport http aivy https://aivymarketing.com/api/mcp

{
  "mcpServers": {
    "aivy": {
      "url": "https://aivymarketing.com/api/mcp",
      "headers": { "Authorization": "Bearer aivy_at_YOUR_KEY" }
    }
  }
}

A chatbot cannot connect by visiting this website. A person adds the MCP URL as a connector in their assistant (or gives their bot a key), and the assistant then calls Aivy's tools.

Authentication

OAuth 2.1 (recommended)

• Aivy is the authorization server. Discovery follows the MCP spec: a 401 carries WWW-Authenticate: Bearer realm="aivy", resource_metadata="…".
• Dynamic client registration at /api/mcp/oauth/register, or a Client ID Metadata Document (an https URL as client_id).
• Authorization code with PKCE S256 (required). The resource parameter is https://aivymarketing.com/api/mcp. Public clients (token_endpoint_auth_method: none).
• The person approves at aivymarketing.com/connect/agent. Tokens come from /api/mcp/oauth/token (authorization_code, refresh_token with rotation).
• The access token is an opaque aivy_at_… grant, not a JWT.

Fixed key

A person creates a key under Settings → AI Assistants. It starts with aivy_at_, is shown once, works for 90 days, and can be replaced or disconnected at any time.

Profiles and scopes

Scopes are ceilings: the person can choose a lower profile, specific brands or all brands (including future ones), and a credit limit. tools/list only returns the tools the grant allows.

Discovery endpoints

Quick start: set up a brand

Call get_setup_status and follow its nextStep. The MCP prompt set_up_my_brand starts this flow.

1. create_brand (name, optional website).
2. start_website_scan → poll get_website_scan — or create_brand_dna_without_website and fill it with update_brand_dna.
3. get_brand_dna, adjust with update_brand_dna, then approve_brand_dna.
4. get_strategy_questions and save_strategy_answers, one chapter at a time.
5. generate_strategy → get_strategy_draft, edit_strategy, approve_strategy.
6. create_content_plan → get_content_plan.

Scans, strategies and plans build in the background for a few minutes; read them again after checkAgainInSeconds instead of starting them again. They cost 9, 5 and 14 credits from the person's Aivy account (about 28 for a full setup). Ask the person before steps that spend credits or approve something.

Quick start: draft and schedule a post

1. get_brand_context for voice and guidelines, list_channels to check the network can publish.
2. upload_media (returns a signed upload URL) or upload_media_from_url.
3. create_post_draft with 1–5 variants and mediaIds. Fix any validation errors.
4. schedule_post (at least 5 minutes ahead) or publish_post, then poll get_publish_status.
5. Later, get_post_metrics for impressions, reach, engagement and clicks.

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "schedule_post",
    "arguments": {
      "brandId": "BRAND_ID",
      "postId": "POST_ID",
      "scheduledAt": "2026-12-01T09:00:00",
      "idempotencyKey": "linkedin-2026-12-01"
    }
  }
}

A timestamp without an offset uses the brand's time zone. dryRun: true returns the payload without sending it.

Tool reference

The minimum profile is shown for each tool. Full input schemas: openapi.json, or tools/list on the MCP server.

47 tools.

Account and usage

Brand setup

Strategy

Content plan

Channels

Posts

Publishing

Media

AI generation

Analytics

Protocol, limits and errors

• Transport: stateless Streamable HTTP. Send JSON-RPC 2.0 with POST; GET (SSE) returns 405. Methods: initialize, ping, tools/list, tools/call, prompts/list, prompts/get.
• MCP versions: 2025-11-25, 2025-06-18, 2025-03-26.
• Rate limits: 300 reads and 60 writes per minute per grant.
• Idempotency: every write takes an idempotencyKey; repeating a call with the same key does not repeat the action.
• Results: { "ok": true, "data": … } or { "ok": false, "error": { "code", "message", "retryable" } }. Codes include invalid_input, permission_denied, conflict, channel_disconnected, already_processing, rate_limited, provider_error and temporarily_unavailable.
• Credits: generation and setup steps spend the person's Aivy credits, capped by the grant's credit limit. get_usage and estimate_generation are free.
• REST: the same tools are available as POST /api/agent/v2/actions/{name} with { "brandId", "idempotencyKey", "input" }, plus read routes under /api/agent/v2/, using the same bearer token. The old /api/agent/v1 is retired (410).

Privacy and safety

• An assistant sees only the brands and actions the person allowed. Settings → AI Assistants shows every connection, its activity and credits used, and Disconnect stops it at once.
• Nothing is published without the Publisher profile; with approval on, every post waits for a person in Aivy.
• Social account passwords and tokens are never returned to an assistant.
• The assistant's provider receives the Aivy data it reads in the chat. See the Privacy policy and Terms.

Questions or partnership requests: info@aivy.cz.