MCP Server Reference

Aimly hosts a remote Model Context Protocol (MCP) server over Streamable HTTP so external AI clients — including Claude, Cursor, Windsurf, and custom agent runtimes — can inspect and operate Aimly Email, Aimly Audit, and Aimly Finder directly.

• Endpoint: https://mcp.aimly.online/
• Transport: Streamable HTTP (MCP)
• OAuth discovery metadata: protected-resource metadata at https://mcp.aimly.online/.well-known/oauth-protected-resource, which points to the authorization server metadata at https://aimly.online/.well-known/oauth-authorization-server

Authentication

Connecting MCP Clients to Aimly

0:00 / 0:00

Aimly's MCP server supports two authentication mechanisms. Both forward requests under your Aimly account identity without duplicating or caching your workspace data on the MCP proxy.

Method 1: OAuth 2.1 + PKCE (recommended for interactive desktop/web clients)

MCP clients that support OAuth 2.1 with S256 PKCE and Dynamic Client Registration (such as Claude Desktop / Claude Connectors and Cursor) can connect using only the server URL:

1. Add https://mcp.aimly.online/ as a remote MCP server in your client.
2. Start the client's Connect / Sign in flow.
3. Approve access in your browser using your Aimly account. The client receives and refreshes OAuth tokens automatically; they grant full access to your account across Email, Audit, and Finder.

Method 2: Bearer API Key (for CLI tools, scripts, and header-configured clients)

Generate a personal Aimly API key on the unified dashboard:

1. Open API Key on the unified dashboard (aimly.online/dashboard, or Account → API Key).
2. Click Generate API Key and copy the aimly_... token immediately — the full secret is displayed only once.

Key lifecycle rules:

• One active key per account — generating a new key immediately revokes any previous key.
• Generation rate limits — subject to a 60-second cooldown between generations and at most 3 generations per hour.
• Revocation — click Revoke on the API Key page at any time if a key may have been exposed.

Pass the key in the Authorization HTTP header:

Authorization: Bearer aimly_<your_api_key>

Example client configuration (mcp.json)

{
  "mcpServers": {
    "aimly": {
      "url": "https://mcp.aimly.online/",
      "headers": {
        "Authorization": "Bearer aimly_replace_with_your_key"
      }
    }
  }
}

Exposed tools and resources

The server registers 113 tools across all three Aimly products plus built-in platform documentation helpers:

Namespace	Capabilities
Email	List/create/update/delete Brands, Mailboxes (rate-limit & signature updates), Leads (CRUD, verification inspection, Finder lead imports), Categories, Campaigns (settings, cloning, enrollment), Templates ({{lead_name}} / {{company_name}} draft generation), Attachments (upload/download via content_base64, campaign/global linking), Automations (predefined steps, draft activation, pause/resume/complete/restart), Sending (queue, schedule, cancel), and Statistics (sends, confirmed reads, replies, bounces, plan status).
Audit	Check Audit quota/access, list connected mailboxes, launch Full audits on connected mailboxes or DNS-only audits by email address, poll or cancel running jobs, inspect per-account audit history and detailed section findings, and download PDF reports (content_base64).
Finder	Check Finder quota/access, list and inspect past or active discovery jobs, stop jobs, and download leads as CSV. Resuming a stopped or failed search requires the dashboard.
Guides & Skills	Tool get_aimly_documentation and MCP resource resource://skills.md provide structured operational playbooks so connected AI agents follow Aimly's exact domain rules automatically.

Browser-cookie key boundary

Third-party AI and Web Search keys configured under Account Integrations live exclusively in encrypted HttpOnly browser cookies and are never transmitted to external MCP clients.

Consequently, MCP clients should use template- and import-driven workflows instead of browser-key AI endpoints:

Unsupported over MCP (400 Bad Request)	Recommended MCP equivalent
Generating AI-written campaign drafts (plain / html AI modes)	Create a Campaign Template ({{lead_name}}, {{company_name}}) via MCP — your MCP client's own LLM can author the template copy — and generate campaign emails from that template.
Creating Personalized with AI automation steps	Create automation steps in Predefined template mode with explicit subject and body copy written by your MCP client.
Starting a brand-new Finder web search, resuming a stopped or failed one, or optimizing a brief	Start or resume web discovery runs in the Finder dashboard UI, then use MCP tools to monitor completion, export CSVs, or import discovered leads into campaigns.

Binary payloads and status handling

• Base64 binary transfers — file uploads (File Manager attachments) and binary downloads (Audit PDF reports, attachment downloads) exchange file bytes encoded as content_base64 alongside filename and MIME metadata. Attachments follow the same 5 MB per-file limit and 10 allowed extensions enforced in the dashboard.
• HTTP & tool error codes:
  • 400 Bad Request — validation error, locked campaign state (for example, enrolling leads while an automation has active/paused executions), or attempting a browser-key AI operation without a template.
  • 401 Unauthorized — missing, expired, or revoked Bearer API key or OAuth access token.
  • 403 Forbidden — plan quota reached or account remediation lock active (call get_email_plan_status to inspect plan limits and remediation status).
  • 404 Not Found — referenced brand, mailbox, lead, campaign, or job ID does not exist in your workspace.
  • 429 Too Many Requests — rate limit reached; wait briefly before retrying.