SociaListSociaList

For AI Agents

Run influencer campaigns programmatically.

SociaList exposes a Model Context Protocol (MCP) server so AI agents can manage businesses, draft and launch matching for campaigns, and negotiate with creators on behalf of small business owners.

Read the spec

New here? Start with this.

An AI agent is a program — like Claude, ChatGPT with tools, or a custom assistant — that can take actions for you instead of just chatting. SociaList lets your agent run influencer campaigns on your behalf: it can create your business profile, draft campaigns, find creators, and reply to their pitches. You stay in control of the things that cost money — funding a campaign and going live still need a click from you. The rest of this page is the technical setup your agent (or its developer) needs to connect.

Just want a plain-English explainer? See the AI Agents section of our FAQ.

What SociaList does

SociaList connects small businesses with local YouTube, Instagram, and TikTok creators for performance-based campaigns. Businesses set a budget and a reach target; the platform matches them with creators, brokers an agreement, and pays out pro-rated to actual views delivered in a 7-day performance window.

How agents connect

The MCP server uses OAuth 2.1 with PKCE and Dynamic Client Registration. Any compliant MCP client (Claude Desktop, the Anthropic Agent SDK, MCP Inspector, or your own) can discover, register, and authenticate without manual setup.

MCP endpoint

https://api.thesocialistapp.com/mcp

Transport

Streamable HTTP (JSON-RPC + SSE)

Resource metadata

https://api.thesocialistapp.com/.well-known/oauth-protected-resource

Authorization server metadata

https://api.thesocialistapp.com/.well-known/oauth-authorization-server

Flow

  1. 1

    Discover

    Fetch /.well-known/oauth-protected-resource to learn the authorization server, supported scopes, and bearer-token requirements.

  2. 2

    Register

    POST to /oauth/register with your client name and redirect URIs to obtain a client_id (RFC 7591 Dynamic Client Registration; no client secret — public client).

  3. 3

    Authorize

    Send the user to /oauth/authorize with PKCE (S256). The user signs in and approves the requested scopes on a consent screen. Only SBO accounts can authorize agent access.

  4. 4

    Exchange

    POST the returned code plus your code_verifier to /oauth/token to receive an access token (1h) and a refresh token (30d). Refresh tokens rotate on every use.

  5. 5

    Call tools

    Send JSON-RPC requests to /mcp with Authorization: Bearer <access_token>. The server returns the standard tools/list and dispatches tools/call against the registered tool set.

Scopes

Agents request the minimum scopes they need. Tokens are opaque and stored hashed.

sbo:read

List and inspect businesses, campaigns, invites, message threads, the influencer directory, and currency/location config.

sbo:write

Create and update businesses and draft campaigns, start matching, respond to pitches, and send messages on behalf of the SBO.

Available tools

Tools are explicitly registered — new backend endpoints do not auto-expose. Money-moving operations (campaign funding and launch) are intentionally excluded until a human-confirmation gate is in place.

Read (sbo:read)

list_businesses

Businesses owned by the authorizing SBO.

get_business

Full business details with aggregated stats.

list_campaigns

Campaigns, optionally filtered by business and status.

get_campaign

Full campaign details.

list_campaign_invites

All invites and pitches for a campaign.

get_inbox

Pitches and invites across campaigns, optionally filtered by status.

get_invite_messages

Message thread between SBO and creator on an invite.

browse_influencers

Paginated influencer directory with niche, location, and platform filters.

list_approved_locations

Supported countries with currency, locale, and budget ranges.

get_currency_config

Currency, budget bounds, and reach multiplier for a country.

list_cold_pitches

Inbound BusinessPitches across the SBO's businesses (creator-initiated, pre-campaign).

get_cold_pitch

One cold pitch with creator card + full conversation thread.

list_notifications

In-app notification feed with cursor pagination, unread + category filters.

get_unread_notification_count

Unread notification count — cheap badge query.

Write (sbo:write)

create_business

Create a business profile.

update_business

Update business fields.

delete_business

Delete a business (rejected if it has active campaigns).

create_draft_campaign

Create a DRAFT campaign. Also accepts from_pitch_id to convert a cold BusinessPitch into a campaign in one call. Rate-limited to 10 per user per day.

update_campaign

Update campaign fields (subject to status).

delete_campaign

Delete a DRAFT campaign.

start_matching

Transition DRAFT → MATCHING and run the matching engine.

revert_campaign_to_draft

Move MATCHING → DRAFT, preserving existing invites.

accept_pitch

Accept a pitch and form a CampaignAgreement (binding).

decline_pitch

Decline a pitch (recoverable via resend_invite).

send_pitch_reply

Reply on a pitch thread without changing invite status.

resend_invite

Re-issue a previously declined invite with a fresh expiration.

send_business_message

Send a free-text message in the invite thread.

reply_to_cold_pitch

Reply on a cold BusinessPitch thread; first reply flips PENDING → REPLIED.

decline_cold_pitch

Silently close a cold pitch (creator not notified, by product design).

mark_notifications_read

Mark specific in-app notifications as read.

mark_all_notifications_read

Bulk-mark every unread notification as read.

Limits & guardrails

  • Campaign creation

    10 draft campaigns per user per UTC day.

  • Token lifetime

    Access tokens last 1 hour; refresh tokens 30 days with rotation on every refresh.

  • PKCE required

    S256 only. Authorization codes are single-use; replay revokes the entire token chain.

  • SBO-only

    Only Small Business Owner accounts can authorize agent access. Influencer-side operations are not yet exposed over MCP.

  • No money movement

    Funding, launching campaigns, and payouts require human confirmation and are not callable by agents.

Quick start

Most MCP-aware clients only need the endpoint URL — they handle discovery and OAuth automatically. The example below shows the raw HTTP calls for clients written from scratch.

1. Register a client
curl -X POST https://api.thesocialistapp.com/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "My Agent",
    "redirect_uris": ["http://localhost:6274/oauth/callback"]
  }'
2. Exchange code for tokens
curl -X POST https://api.thesocialistapp.com/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "authorization_code",
    "code": "<code from /oauth/authorize>",
    "code_verifier": "<your PKCE verifier>",
    "redirect_uri": "http://localhost:6274/oauth/callback",
    "client_id": "<client_id from registration>"
  }'
3. Call a tool
curl -X POST https://api.thesocialistapp.com/mcp \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "list_businesses", "arguments": {} }
  }'

Need an account?

Agents act on behalf of an SBO user. Sign up as a business owner, complete onboarding, then connect your agent.