Integrate SofAds with an AI assistant (MCP)

SofAds has an MCP server for publishers. MCP (Model Context Protocol) is the standard way for coding assistants to use outside tools. When you connect your assistant to it, the assistant can work on your SofAds account while it edits your code. It can add the SDK to your TV app, create the placements your code calls, register your TV as a test device and check that SofAds sees the app.

The server works with your organization's API key, so the assistant can only see and change your own apps.

What the assistant can do

Tool	What it does	Scope
list_apps, get_app	Shows your apps with their app IDs, listings, placements and test devices.	apps:read
get_sdk_setup	Gives the integration steps for one app on one platform: the SDK file with its checksum, the init and show calls with your placement keys, and the full setup guide for that platform.	apps:read
read_docs	Reads any publisher page of these docs as Markdown.	apps:read
check_integration	Shows TVs running the app right now, sessions and test ads in the last 7 days, and problems the SDK reported, each with its fix.	apps:read
create_app, add_listing	Creates an app and adds a store listing per platform, with the app's own ID from config.xml or appinfo.json.	apps:write
create_placement, update_placement, delete_placement	Manages placements: key, type, frequency caps, platforms, skip and close timing, and the reward amount and names.	apps:write
add_test_device, remove_test_device	Registers a TV by the install ID from the debug overlay.	apps:write
get_report	Shows revenue or usage, like the management API reports.	reports:read

There are no tools for money, payouts, users or API keys. Floors are set by SofAds, as in the dashboard. You upload the reward icon in the dashboard.

The server also has a prompt, integrate_sofads, that walks the assistant through a full integration. Every docs page is also available as a resource (sofads://docs/<page>).

1. Create an API key

In the publisher dashboard, open API keys and create a key. Only owners and admins can create keys. Choose the scopes:

• apps:read and apps:write let the assistant set up apps, listings, placements and test devices.
• With apps:read alone, the assistant can only read and advise.
• Add reports:read if it may also read revenue and usage.

The key is shown once. Keep it out of your app's code and out of git: TV app packages are easy to unpack. You can revoke a key at any time on the same page.

2. Connect your assistant

The server address is https://api.sofads.com/mcp. It uses Streamable HTTP, and the key goes in the Authorization header.

Claude Code:

claude mcp add --transport http sofads https://api.sofads.com/mcp \
  --header "Authorization: Bearer $SOFADS_API_KEY"

Cursor (.cursor/mcp.json, with the key in the environment variable SOFADS_API_KEY):

{
  "mcpServers": {
    "sofads": {
      "url": "https://api.sofads.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SOFADS_API_KEY}" }
    }
  }
}

VS Code (.vscode/mcp.json, which asks for the key once and stores it securely):

{
  "inputs": [{ "type": "promptString", "id": "sofads-key", "description": "SofAds API key", "password": true }],
  "servers": {
    "sofads": {
      "type": "http",
      "url": "https://api.sofads.com/mcp",
      "headers": { "Authorization": "Bearer ${input:sofads-key}" }
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.sofads]
url = "https://api.sofads.com/mcp"
bearer_token_env_var = "SOFADS_API_KEY"

Other assistants work the same way if they support remote MCP servers with a bearer token header. Assistants that only connect through a sign-in flow (OAuth) can't connect yet.

3. Ask for the integration

Open your TV app's project and ask, for example:

• "Add SofAds to this Tizen game. Put an interstitial after each level and a rewarded ad for an extra life."
• "Which ad moments would you suggest in this app? Create the placements I approve."
• "I added my TV as a test device. Check the SofAds integration and fix what it reports."

In Claude Code you can also run the prompt directly: /mcp__sofads__integrate_sofads.

The assistant asks you whether the app is made for children. That answer is your own declaration, so it never guesses. Until a listing is live, the app only gets test ads: they are never billed, so you can build and test right away.

Good to know

• Placement keys connect code and settings. The key in SofAds.showInterstitial({ placement: "level_break" }) must match a placement in SofAds. A key without its own placement uses the default placement of its type.
• Changes reach TVs within about a minute. This applies to placements, caps and test devices. The code itself only reaches users with a new release, so check the release checklist before you submit.
• The assistant changes your live account. Everything it does shows up in the dashboard right away. Check its placement changes as you would a colleague's.

The management API

The same API key also works with the REST API at https://api.sofads.com/v1/: GET and POST /v1/apps, POST /v1/listings, and GET /v1/reports/revenue, usage and earnings. You can use it for scripts and CI. Send the key in the Authorization: Bearer header.

Keep reading

• SDK reference
• Test ads and test devices
• Troubleshooting