Genie MCP

The Genie MCP lets AI editors read and write GenieOS safely on behalf of a logged-in user. It speaks the Model Context Protocol over stateless streamable HTTP, with bearer authentication and per-tool scopes. Supported today: Cursor, Claude Code, Claude Desktop, Codex, ChatGPT Developer Mode, Continue, Zed — plus any MCP 1.0 client.

The endpoint:

https://mcp.genieos.pro/v1

Why MCP, not "an integration"

A plugin pattern is one editor at a time. MCP gives every editor that speaks the protocol the same surface — and gives GenieOS schema contracts as tool schemas, so the agent literally cannot propose a malformed template send.

The result for the user: "tell Cursor to ship a launch sequence" actually ships a launch sequence with the right variables, in the right state machine, with audit trail.

Install

The fastest way is the Developer Console in app.genieos.pro → Developers (Cursor deeplink + copy-paste snippets for every other client). Reveal your gos_* key once, then pick the tab for your editor. If you\u2019d rather wire it by hand:

{
  "mcpServers": {
    "genieos": {
      "url": "https://mcp.genieos.pro/v1",
      "headers": {
        "Authorization": "Bearer gos_…"
      }
    }
  }
}

claude mcp add --transport http \
  --header "Authorization: Bearer gos_…" \
  genieos https://mcp.genieos.pro/v1

claude mcp list

{
  "mcpServers": {
    "genieos": {
      "command": "npx",
      "args": ["-y", "@genie-os/mcp"],
      "env": {
        "GENIEOS_API_KEY": "gos_…"
      }
    }
  }
}

export GENIEOS_API_KEY='gos_…'
codex mcp add genieos \
  --url https://mcp.genieos.pro/v1 \
  --bearer-token-env-var GENIEOS_API_KEY

codex mcp list

{
  "name": "genieos",
  "transport": {
    "type": "streamable-http",
    "url": "https://mcp.genieos.pro/v1",
    "headers": {
      "Authorization": "Bearer gos_…"
    }
  }
}

{
  "context_servers": {
    "genieos": {
      "command": {
        "path": "npx",
        "args": ["-y", "@genie-os/mcp"]
      },
      "settings": {
        "env": {
          "GENIEOS_API_KEY": "gos_…"
        }
      }
    }
  }
}

npx -y @genie-os/mcp
# stdin/stdout speaks JSON-RPC; Authorization read from GENIEOS_API_KEY.

POST https://mcp.genieos.pro/v1
Authorization: Bearer gos_…
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

Available tools

Every tool is a thin wrapper around the REST API with the same auth and the same schema-contract enforcement. Live catalogue today: 64 tools (call tools/list for the authoritative JSON Schema).

Workspace & brand

Email templates & sends

Pages

Sequences

Transactional SMS

Transactional socials

Organic social

Marketing OS, campaigns & lists

Approvals, links & webhooks

list_utm_suggestions

Returns prior utm_source / utm_medium / utm_campaign / utm_content / utm_term values used on workspace short links, frequency-ranked (same history the Links designer autocomplete uses). Requires links:read.

Agent habit: call this before create_short_link. Offer matching prior values to the operator so taxonomy stays consistent (newsletter not a new Newsletter spelling).

list_short_links

Lists existing tracked links (slug, redirectUrl, destination, utm, clicks). Useful to avoid minting duplicates. Requires links:read.

create_short_link

Mints a tracked short link (1 credit). Requires links:write. Optional utm is stamped onto the redirect destination at click time — so a chatbot can take a list of sites and mint attributed links in one pass. Prefer reusing values from list_utm_suggestions when the operator agrees. Password, expiry, scheduled go-live, and route rules (country / city / device / platform) are available on every tier.

{
  "destinationUrl": "https://acme.com/sale",
  "slug": "summer",
  "label": "Summer sale",
  "password": "gate-phrase",
  "utm": {
    "source": "newsletter",
    "medium": "email",
    "campaign": "summer-2026",
    "content": "hero-cta"
  }
}

Returns redirectUrl (https://gogen.ie/{slug}), linkId, and click counters at zero. There is no bulk endpoint — call once per destination. Slug collisions return an error; omit slug or retry with another value.

Use get_short_link / update_short_link to read or patch an existing link (including clearPassword, clearExpiresAt, clearScheduledGoLiveAt, clearRouteRules). Use read_link_analytics for click cards. For QR: create_qr_design → render_qr_design with format (svg | png | webp | png-print | pdf) and optional saveToAssets. Print PDF (bleed) costs 5 credits; hi-res PNG 2; SVG / PNG / WebP free. Prefer compose_template when the operator gave a brief; use create_template only for a blank canvas. Both need templates:write (Full / custom keys). Hero image gen on compose is off unless includeHeroImage: true.

Organic social tools require social:posts:read|write|publish (see Authentication). Only company / workspace networks are returned — never personal LinkedIn or personal X profiles. create_social_post supports mode: "copy" (supply caption) and mode: "compose" (Genie writes from a brief). Prefer create_social_post with scheduleAt when the time is known; always confirm before publish: true or publish_social_post. Native X with a URL in the caption or linkUrl costs 4 credits (social-post-publish-url) instead of 1. Pass refresh: true on get_social_post_analytics to poll live metrics. Call refresh_social_networks after the operator connects a new account.

Call read_marketing_strategy (and list_icps) before drafting campaigns. Prefer spawn_creation + approve_creation_strategy over hand-wiring every channel when the brief is campaign-shaped.

Tools that mutate require a key with the matching scope. The MCP installer offers presets — Read, Send, Author, Full — so the human in the loop chooses the agent\u2019s blast radius.

How the contract flows through

When tools/list is called, GenieOS returns each tool\u2019s JSON Schema including the per-template variable schema for the templates the key can see. So send_transactional\u2019s schema looks roughly like:

{
  "name": "send_transactional",
  "description": "Send a single transactional message via a published template.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "to": { "type": "string", "format": "email" },
      "template": {
        "type": "string",
        "enum": ["welcome", "order_confirm", "password_reset"]
      },
      "variables": {
        "oneOf": [
          { "title": "welcome",        "type": "object", "required": ["first_name", "plan"], "properties": { ... } },
          { "title": "order_confirm",  "type": "object", "required": ["order_total"],         "properties": { ... } },
          { "title": "password_reset", "type": "object", "required": ["reset_url"],           "properties": { ... } }
        ]
      }
    },
    "required": ["to", "template", "variables"]
  }
}

The agent gets red squiggles for missing variables, just like a TypeScript developer would. This is the killer feature.

Auditing

Every MCP call lands in the audit log with actor.kind = "mcp", actor.client (e.g. cursor/0.42.0), and actor.user (the human who installed the key). Replay it from the dashboard or:

genie logs tail --actor mcp

Revoke

gos_mcp_* keys can be revoked from app.genieos.pro → Developers → MCP at any time; revocation is instant. The next agent call sees 401 invalid_api_key and the editor shows a re-auth prompt.

What\u2019s next

• MCP Resources for static knowledge — your domain\u2019s style guide, brand voice, do-not-send list — coming in Q3 2026.
• MCP Prompts for canned workflows — "draft a launch sequence", "audit last week\u2019s sends" — coming in Q3 2026.

If you\u2019re building MCP-shaped tooling and want feedback on what the contract surface should look like for your domain, hello@genieos.pro.