📘 DEVELOPER & AGENT DOCUMENTATION

Nuntior API & 12-Tool MCP Reference

Connect any MCP-compatible AI agent (Cursor, Claude Desktop, Claude Code, Grok Bot, OpenClaw, Hermes) directly to https://nuntior.com/mcp or call our deterministic REST endpoints at https://nuntior.com/v1/*.

1. Claude Desktop / Cursor MCP Config

Add Nuntior's remote Streamable HTTP MCP endpoint to ~/.cursor/mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "nuntior": {
      "type": "streamable-http",
      "url": "https://nuntior.com/mcp",
      "headers": {
        "Authorization": "Bearer ntr_live_YOUR_API_KEY"
      }
    }
  }
}

2. Test Live MCP Server via cURL

Query all 12 tools or invoke posts_publish with X Smart Link optimization right now:

curl -X POST https://nuntior.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

REST API Endpoints

Method & Path	Description
`GET /health`	Service health check, version, domain, and active MCP tool count.
`GET /v1/tools`	Full JSON Schema catalog of all 12 semantic MCP tools + high-margin value-add capabilities.
`POST /mcp` & `GET /mcp`	Streamable HTTP JSON-RPC 2.0 MCP endpoint (`initialize`, `ping`, `tools/list`, `tools/call`).
`POST /v1/posts`	Publish, schedule, or cross-post with automatic X Smart Link Optimizer (`first_reply`).
`POST /v1/x-smart-link/preview`	Preview how Nuntior splits inline URLs into a 1st reply and calculates X API savings ($0.20 → $0.03).
`GET /v1/profiles`	List multi-tenant brand profiles and default media/link settings.
`GET /v1/accounts`	List connected social accounts and Hybrid OAuth health status.
`GET /oauth/:platform/callback`	OAuth 2.0 authorization callback endpoint for Meta, TikTok, LinkedIn, Google, X, and Reddit.
`POST /data-deletion`	Meta/Facebook-compliant signed Data Deletion Request callback returning `{ url, confirmation_code }`.

Complete 12-Tool Semantic MCP Schemas

`1. profiles_manage`

JSON-RPC tools/call

Manage multi-tenant brand/client profiles (list, create, update, delete) and default X Smart Link & Media settings.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "list",
        "create",
        "update",
        "delete"
      ]
    },
    "profileId": {
      "type": "string",
      "description": "Profile ID (for update/delete)"
    },
    "name": {
      "type": "string",
      "description": "Brand or client display name"
    },
    "handleSlug": {
      "type": "string",
      "description": "URL-friendly slug"
    },
    "timezone": {
      "type": "string",
      "default": "Europe/Madrid"
    },
    "defaultXLinkStrategy": {
      "type": "string",
      "enum": [
        "inline",
        "first_reply",
        "bio"
      ],
      "default": "first_reply"
    },
    "autoAdjustMedia": {
      "type": "boolean",
      "default": true
    }
  },
  "required": [
    "action"
  ]
}

`2. accounts_manage`

JSON-RPC tools/call

Manage connected social accounts with Hybrid OAuth Vault (1-click Managed OAuth OR zero-markup AES-256-GCM BYOK custom_client_id/secret) and continuous account_health monitoring.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "list",
        "connect_oauth",
        "connect_byok",
        "health_check",
        "account_health",
        "disconnect"
      ]
    },
    "profileId": {
      "type": "string"
    },
    "accountId": {
      "type": "string"
    },
    "platform": {
      "type": "string",
      "enum": [
        "x",
        "linkedin",
        "instagram",
        "facebook",
        "threads",
        "tiktok",
        "youtube",
        "bluesky",
        "mastodon",
        "farcaster",
        "reddit",
        "pinterest",
        "google_business",
        "telegram",
        "discord",
        "ghost",
        "wordpress",
        "webflow"
      ]
    },
    "username": {
      "type": "string"
    },
    "customClientId": {
      "type": "string",
      "description": "BYOK OAuth App Client ID (encrypted at rest via AES-256-GCM)"
    },
    "customClientSecret": {
      "type": "string",
      "description": "BYOK OAuth App Client Secret (encrypted at rest via AES-256-GCM)"
    },
    "accessToken": {
      "type": "string"
    },
    "refreshToken": {
      "type": "string"
    }
  },
  "required": [
    "action"
  ]
}

`3. posts_publish`

JSON-RPC tools/call

Publish now, schedule, queue, or cross-post across 18 networks with automatic X Smart Link Optimizer (inline | first_reply | bio) cutting X link API costs by 85% ($0.03 vs $0.20) and FFmpeg media auto-fit.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "publish_now",
        "schedule",
        "queue",
        "cross_post"
      ]
    },
    "profileId": {
      "type": "string"
    },
    "content": {
      "type": "string",
      "description": "Post text (may include URLs to optimize on X)"
    },
    "platforms": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "x",
          "linkedin",
          "instagram",
          "facebook",
          "threads",
          "tiktok",
          "youtube",
          "bluesky",
          "mastodon",
          "farcaster",
          "reddit",
          "pinterest",
          "google_business",
          "telegram",
          "discord",
          "ghost",
          "wordpress",
          "webflow"
        ]
      }
    },
    "scheduledFor": {
      "type": "string",
      "description": "ISO-8601 timestamp when scheduling"
    },
    "mediaAssetIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "xLinkStrategy": {
      "type": "string",
      "enum": [
        "inline",
        "first_reply",
        "bio"
      ],
      "default": "first_reply",
      "description": "Moves links on X to 1st reply to save $0.17/post ($0.20 -> $0.03 or $0 BYOK) and boost reach."
    },
    "autoAdjustMedia": {
      "type": "boolean",
      "default": true
    },
    "authModeOverride": {
      "type": "string",
      "enum": [
        "managed",
        "byok"
      ]
    }
  },
  "required": [
    "action",
    "content",
    "platforms"
  ]
}

`4. posts_manage`

JSON-RPC tools/call

List, inspect, update, delete, or retry scheduled and published posts.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "list",
        "get",
        "update",
        "delete",
        "retry_failed"
      ]
    },
    "profileId": {
      "type": "string"
    },
    "postId": {
      "type": "string"
    },
    "statusFilter": {
      "type": "string"
    },
    "content": {
      "type": "string"
    },
    "scheduledFor": {
      "type": "string"
    }
  },
  "required": [
    "action"
  ]
}

`5. media_pipeline`

JSON-RPC tools/call

Edge FFmpeg Media Pipeline + Cloudflare R2 zero-egress presigner: automatic video reframing (9:16 Reels/TikTok/Shorts, 16:9 X/LinkedIn), AI clip extraction, and media_generate.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "presign_upload",
        "auto_fit_video",
        "extract_clips",
        "media_generate",
        "check_status"
      ]
    },
    "profileId": {
      "type": "string"
    },
    "fileName": {
      "type": "string"
    },
    "mimeType": {
      "type": "string"
    },
    "sizeBytes": {
      "type": "number"
    },
    "mediaAssetId": {
      "type": "string"
    },
    "prompt": {
      "type": "string",
      "description": "Prompt or template spec for media_generate add-on"
    },
    "targetAspectRatios": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "9:16",
          "16:9",
          "1:1",
          "4:5"
        ]
      }
    },
    "clipCount": {
      "type": "number"
    }
  },
  "required": [
    "action"
  ]
}

`6. inbox_messages`

JSON-RPC tools/call

Unified Social & Messaging Inbox across LinkedIn, X DMs, Instagram, Threads, Telegram, and WhatsApp (list_threads, read_thread, reply, mark_read).

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "list_threads",
        "read_thread",
        "reply",
        "mark_read"
      ]
    },
    "profileId": {
      "type": "string"
    },
    "platform": {
      "type": "string",
      "enum": [
        "x",
        "linkedin",
        "instagram",
        "facebook",
        "threads",
        "tiktok",
        "youtube",
        "bluesky",
        "mastodon",
        "farcaster",
        "reddit",
        "pinterest",
        "google_business",
        "telegram",
        "discord",
        "ghost",
        "wordpress",
        "webflow"
      ]
    },
    "threadId": {
      "type": "string"
    },
    "replyBody": {
      "type": "string"
    },
    "unreadOnly": {
      "type": "boolean"
    }
  },
  "required": [
    "action"
  ]
}

`7. comments_moderate`

JSON-RPC tools/call

List, reply, hide, delete post comments, or configure an automatic viral Auto-Plug reply when a post crosses N likes.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "list",
        "reply",
        "hide",
        "delete",
        "auto_plug"
      ]
    },
    "profileId": {
      "type": "string"
    },
    "postId": {
      "type": "string"
    },
    "commentId": {
      "type": "string"
    },
    "replyText": {
      "type": "string"
    },
    "autoPlugTriggerLikes": {
      "type": "number",
      "default": 25
    },
    "autoPlugMessage": {
      "type": "string"
    }
  },
  "required": [
    "action"
  ]
}

`8. analytics_query`

JSON-RPC tools/call

Unified cross-network analytics & social_listen: account overview, post performance, audience growth, AI best times to publish, and real-time keyword/intent listening.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "account_overview",
        "post_metrics",
        "audience_growth",
        "best_times",
        "social_listen"
      ]
    },
    "profileId": {
      "type": "string"
    },
    "platform": {
      "type": "string",
      "enum": [
        "x",
        "linkedin",
        "instagram",
        "facebook",
        "threads",
        "tiktok",
        "youtube",
        "bluesky",
        "mastodon",
        "farcaster",
        "reddit",
        "pinterest",
        "google_business",
        "telegram",
        "discord",
        "ghost",
        "wordpress",
        "webflow"
      ]
    },
    "postId": {
      "type": "string"
    },
    "query": {
      "type": "string",
      "description": "Keyword or brand query for social_listen"
    },
    "periodDays": {
      "type": "number",
      "default": 30
    }
  },
  "required": [
    "action"
  ]
}

`9. ads_campaigns`

JSON-RPC tools/call

Manage paid social campaigns and organic-to-paid post boosting across Meta Ads, LinkedIn Ads, X Ads, and TikTok Spark Ads with 0% ad-spend tax.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "list",
        "create",
        "pause",
        "resume",
        "boost_post",
        "metrics"
      ]
    },
    "profileId": {
      "type": "string"
    },
    "campaignId": {
      "type": "string"
    },
    "platform": {
      "type": "string",
      "enum": [
        "x",
        "linkedin",
        "instagram",
        "facebook",
        "threads",
        "tiktok",
        "youtube",
        "bluesky",
        "mastodon",
        "farcaster",
        "reddit",
        "pinterest",
        "google_business",
        "telegram",
        "discord",
        "ghost",
        "wordpress",
        "webflow"
      ]
    },
    "name": {
      "type": "string"
    },
    "objective": {
      "type": "string",
      "enum": [
        "engagement",
        "traffic",
        "leads",
        "awareness"
      ]
    },
    "dailyBudgetUsd": {
      "type": "number"
    },
    "postIdToBoost": {
      "type": "string"
    },
    "targeting": {
      "type": "object"
    }
  },
  "required": [
    "action"
  ]
}

`10. blogs_publish`

JSON-RPC tools/call

Publish or update long-form SEO articles directly to Ghost, WordPress, or Webflow CMS before cross-posting social snippets.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "list_sites",
        "publish_article",
        "update_article"
      ]
    },
    "profileId": {
      "type": "string"
    },
    "platform": {
      "type": "string",
      "enum": [
        "ghost",
        "wordpress",
        "webflow"
      ]
    },
    "articleId": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "markdownBody": {
      "type": "string"
    },
    "slug": {
      "type": "string"
    },
    "canonicalUrl": {
      "type": "string"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "publishStatus": {
      "type": "string",
      "enum": [
        "draft",
        "published"
      ]
    }
  },
  "required": [
    "action"
  ]
}

`11. telecom_numbers`

JSON-RPC tools/call

Provision dedicated telecom phone numbers ($1.50/mo vs $59/mo legacy bundles) for SMS, WhatsApp Business, and SIP/WebRTC Voice AI Agents.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "search_available",
        "provision",
        "configure_sip_voice_agent",
        "list"
      ]
    },
    "profileId": {
      "type": "string"
    },
    "countryCode": {
      "type": "string",
      "default": "ES"
    },
    "phoneNumber": {
      "type": "string"
    },
    "numberId": {
      "type": "string"
    },
    "sipTrunkUri": {
      "type": "string"
    },
    "voiceAgentPrompt": {
      "type": "string"
    }
  },
  "required": [
    "action"
  ]
}

`12. telecom_messaging`

JSON-RPC tools/call

Send transactional SMS ($0.004/msg), WhatsApp Business Cloud templates, or place outbound AI Voice calls via Nuntior Telecom.

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "send_sms",
        "send_whatsapp_template",
        "place_call",
        "logs"
      ]
    },
    "profileId": {
      "type": "string"
    },
    "fromNumber": {
      "type": "string"
    },
    "toNumber": {
      "type": "string"
    },
    "body": {
      "type": "string"
    },
    "templateName": {
      "type": "string"
    },
    "voiceScriptOrAgentId": {
      "type": "string"
    }
  },
  "required": [
    "action"
  ]
}