Profiles

A profile is one client’s presence on Native: its brand settings, its connected social accounts and its posts. The tools call it a brand, so a profile’s id is the brandId that every other tool takes.

Each client gets a workspace of its own with one profile in it. The workspace’s id is companyId. You make the profile with create_profile, watch it with get_profile, and end the service with deactivate_profile or delete_profile.

You can create connect links for the client’s social accounts while the profile builds. The whole sequence, from onboarding to publishing, is in the flow.

Creates a profile for a client from its website. Native makes a workspace of its own for the client, on your plan, with no browser and no checkout. It answers at once and builds the profile in the background. It reads the website and fills in the business profile, the brand look, knowledge, products and writing style, the same as for a customer who signs up in the Native app.

Only a partner token can call it. A token without partner access does not see it in tools/list, and calling it anyway fails as an unknown tool. It changes data, so the token needs the mcp:write scope (see Authentication).

import type { Client } from "@modelcontextprotocol/sdk/client/index.js";

// client: an MCP SDK client connected with a partner token.
async function createProfile(client: Client) {
  const result = await client.callTool(
    {
      name: "create_profile",
      arguments: {
        websiteUrl: "https://harbourstreetbakery.example",
        name: "Harbour Street Bakery",
        externalId: "client-4821",
      },
    },
    undefined,
    { timeout: 150_000 },
  );

  const data = (result.structuredContent as { data: any } | undefined)?.data;
  if (result.isError) {
    // data = { ok: false, error: { code, message, retryable, ... } }
    throw new Error("create_profile failed: " + data.error.code);
  }

  // Keep these next to your own id for the client.
  return { brandId: data.brandId, companyId: data.companyId, status: data.status };
}

{
  "data": {
    "brandId": "3f6c2a9e-5b7d-4e1a-9c2f-7a1d8e4b6c05",
    "companyId": "b8e1d0c4-2f3a-4c5d-9e6f-0a1b2c3d4e5f",
    "status": "building",
    "created": true
  }
}

externalId makes the call idempotent. A repeat with the same externalId answers with the profile the first call made, with created: false, whatever else it sends. It never makes a second workspace for the same externalId.

A repeat is also the only way to retry a failed build. Call again with the same externalId and the build restarts where it stopped. The answer then says building again.

A repeat always builds from the website the first call sent, so it cannot fix a wrong address. No partner tool can change a profile’s website yet. Contact Native if the first address was wrong.

invalid_website_url carries one of these codes in websiteRefusal. The field is left out when Native sends a reason the gateway does not know.

{
  "data": {
    "ok": false,
    "error": {
      "code": "invalid_website_url",
      "message": "That website address was refused, so no profile was created; websiteRefusal says why: BLOCKED_DOMAIN is a social media or platform address rather than the customer's own site, URL_NOT_REACHABLE does not resolve or refused the connection, URL_UNSAFE is flagged as harmful, URL_NOT_ALLOWED points at a private address. Send the customer's own website",
      "retryable": false,
      "websiteRefusal": "BLOCKED_DOMAIN"
    }
  }
}

It can also return the errors every tool can return.

While the build runs, get_profile reports onboarding.status as building, readiness.canGenerate as false, and the blocker profile_not_ready.

Until the build is ready, every tool that generates refuses the profile with profile_not_ready: create_posts, generate_caption, generate_image, regenerate_post_image, ad generation, and create_draft when it is sent a prompt or includeImage: true. That includes a profile whose build has failed. A create_draft with your own caption is not refused. Connecting the client’s accounts and publishing are not held up either.

Poll get_profile about once a minute until onboarding.status is ready or failed. It usually takes 10 to 30 minutes. profile_not_ready is retryable, so a call refused for it can be made again unchanged once the profile is ready.

{
  "data": {
    "brandId": "3f6c2a9e-5b7d-4e1a-9c2f-7a1d8e4b6c05",
    "brandName": "Harbour Street Bakery",
    "companyId": "b8e1d0c4-2f3a-4c5d-9e6f-0a1b2c3d4e5f",
    "isActive": true,
    "defaultPlatform": null,
    "generationPlatforms": [],
    "storyDestinations": [],
    "socialProvider": "ZERNIO",
    "channels": [],
    "readiness": {
      "canGenerate": false,
      "canPublish": false,
      "blockers": [
        "profile_not_ready",
        "no_channel_connected"
      ]
    },
    "onboarding": {
      "status": "building"
    }
  }
}

import type { Client } from "@modelcontextprotocol/sdk/client/index.js";

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

async function waitForProfile(client: Client, brandId: string) {
  for (;;) {
    const result = await client.callTool(
      { name: "get_profile", arguments: { brandId } },
      undefined,
      { timeout: 150_000 },
    );
    const data = (result.structuredContent as { data: any } | undefined)?.data;

    if (result.isError) {
      if (!data.error.retryable) throw new Error("get_profile failed: " + data.error.code);
    } else {
      const onboarding = data.onboarding;
      // No onboarding field: create_profile did not build this profile.
      if (!onboarding || onboarding.status === "ready") return data;
      if (onboarding.status === "failed") {
        // Retry: call create_profile again with the same externalId.
        throw new Error("build failed: " + onboarding.error);
      }
    }
    await sleep(60_000);
  }
}

A failed build reports a code in onboarding.error. Treat the list as open: Native can add codes. A repeat create_profile restarts the build and answers building, so read the code from get_profile before you retry.

Every one of them is retried the same way: call create_profile again with the same externalId. The build picks up where it stopped.

Shows what a profile can do right now: its connected channels and their health, the channels it can publish to, and whether it can generate and publish. Call it while a build runs, before you schedule, and once a day to catch accounts that need reconnecting.

The output can hold more fields than these. Ignore any you do not use.

A profile create_profile built, once it is ready and has one Instagram account connected. The onboarding field is in development.

{
  "data": {
    "brandId": "3f6c2a9e-5b7d-4e1a-9c2f-7a1d8e4b6c05",
    "brandName": "Harbour Street Bakery",
    "companyId": "b8e1d0c4-2f3a-4c5d-9e6f-0a1b2c3d4e5f",
    "isActive": true,
    "defaultPlatform": "INSTAGRAM",
    "generationPlatforms": [
      "instagram"
    ],
    "storyDestinations": [
      "instagram_stories"
    ],
    "socialProvider": "ZERNIO",
    "channels": [
      {
        "platform": "instagram",
        "displayName": "Harbour Street Bakery",
        "username": "harbourstreetbakery",
        "profileUrl": "https://www.instagram.com/harbourstreetbakery",
        "health": "connected",
        "healthReason": null,
        "connectedAt": "2026-10-12T09:41:07.000Z",
        "tokenRefreshInDays": 58,
        "tokenExpiresAt": "2026-12-09T09:41:07.000Z",
        "scopes": null,
        "missingScopes": null,
        "canPost": true,
        "canFetchAnalytics": true
      }
    ],
    "readiness": {
      "canGenerate": true,
      "canPublish": true,
      "blockers": []
    },
    "onboarding": {
      "status": "ready"
    }
  }
}

readiness.blockers holds codes, not sentences. Branch on them, and treat the list as open: Native can add codes.

get_profile returns only the errors every tool can return. A brandId that does not exist, or is not yours, gets not_found or forbidden.

Keep the brandId and companyId that create_profile returns next to your own externalId. Calling create_profile again with the same externalId gives them back too, but it is not a plain read: it restarts a failed build.

Two existing tools list what a token can reach. New, in development: with a partner token, they list only your own clients’ workspaces. That scoping arrives with partner access.

There is no cursor. A call returns at most 200 workspaces, and truncated says when more matched. With more clients than that, narrow with query, or look profiles up in your own records.

Both tools return only the errors every tool can return. list_brands answers forbidden for a workspace that is not yours.

Two tools end the service for a client. Both run in the background. The first call schedules the work and answers at once. Calling again with the same brandId reports progress, so both are safe to repeat. Poll about every 30 seconds until the status is final. It usually takes a few minutes.

Both are partner only, and both need the mcp:write scope. As with create_profile, a token without partner access does not see them in tools/list, and calling one anyway fails as an unknown tool. Both refuse with stripe_billed_workspace when the workspace pays for its own Native subscription: that subscription has to be cancelled in Native.

Ends the service for a client. Every scheduled post is withdrawn to unscheduled, and keeps its date. The client’s social accounts are disconnected and removed at the provider. Every profile in the workspace is made inactive, and the workspace loses its plan, so no tool can generate, schedule or publish for it.

Nothing is deleted. But there is no reactivate tool, and reconnecting needs the client to log in with each platform again. Treat it as the end of the service.

{
  "data": {
    "companyId": "b8e1d0c4-2f3a-4c5d-9e6f-0a1b2c3d4e5f",
    "status": "deactivation_scheduled",
    "unscheduledPosts": 0
  }
}

{
  "data": {
    "companyId": "b8e1d0c4-2f3a-4c5d-9e6f-0a1b2c3d4e5f",
    "status": "deactivated",
    "unscheduledPosts": 4
  }
}

Permanently erases a client: the whole workspace, every profile in it, its posts, pictures, videos and uploaded files, its brand settings and its onboarding data. Native disconnects the social accounts and removes them at the provider first. This is the call for a GDPR erasure request.

After the erasure, the client’s image URLs stop resolving.

import type { Client } from "@modelcontextprotocol/sdk/client/index.js";

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

// The first call schedules the erasure. Every later call reports progress.
async function deleteProfile(client: Client, brandId: string) {
  for (;;) {
    const result = await client.callTool(
      { name: "delete_profile", arguments: { brandId, confirm: true } },
      undefined,
      { timeout: 150_000 },
    );
    const data = (result.structuredContent as { data: any } | undefined)?.data;

    if (result.isError) {
      if (!data.error.retryable) throw new Error("delete_profile failed: " + data.error.code);
    } else if (data.status === "deleted") {
      return data;
    }
    await sleep(30_000);
  }
}

{
  "data": {
    "companyId": "b8e1d0c4-2f3a-4c5d-9e6f-0a1b2c3d4e5f",
    "deleted": true,
    "status": "deletion_scheduled"
  }
}

Any tool on this page can also return bad_request, not_found, forbidden, subscription_required, internal_error, upstream_timeout, upstream_unavailable, upstream_identity_failed, identity_provider_unavailable and upstream_<status>. The tools that change data can return writes_disabled. A partner token whose client Native has not set up gets partner_not_found on every call. With a partner token, any call can also get partner_downstream_auth_failed, which is retryable.

Branch on error.code, never on message, and respect retryable. An argument that breaks a tool’s input schema is refused by the MCP SDK before the tool runs, with a validation error instead of the error envelope. That covers an argument the tool does not take, and a brandId that is not a UUID on deactivate_profile or delete_profile. Errors explains the codes.