OSMOS Marketing API MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OSMOS Marketing API MCP Server Create a new SPA campaign 'Summer Sale' with budget 5000"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OSMOS Marketing API MCP Server
Model Context Protocol server that exposes the OSMOS Marketing API registry as callable tools, so an AI agent can discover endpoints and make real API calls.
Structure
api_mcp/
├── server.mjs # MCP server (stdio transport)
├── package.json
├── registry/
│ ├── index.json # Root registry (lists services)
│ ├── service/
│ │ └── service.json # Service definition (base URL, auth, hierarchy)
│ └── endpoints/
│ ├── index.json # Endpoint index (15 endpoints)
│ └── *.json # One file per endpoint (OpenAPI-derived)Related MCP server: Relay
How it works
server.mjsloads the registry JSON files at startup.It registers a tool for every endpoint in
registry/endpoints/index.json(named by convertingidto snake_case, e.g.create-spa-campaign→create_spa_campaign).Each endpoint tool accepts path params, query params, an optional
body, plusx_tokenandx_retailer_idauth headers.Calling a tool performs the real HTTP request against
https://apiv2.onlinesales.ai/marketing/v1/advertiserand returns status + parsed response.
Built-in tools
list_endpoints— list all endpoints (method, path, summary)get_service_details— service definition (base URL, auth, hierarchy)get_endpoint_definition— full schema for one endpoint by id
Resources
osmos://service— service definitionosmos://endpoints— endpoint index
Prompt
campaign-hierarchy— explains the campaign hierarchy before acting
Run
npm install
npm startThe server speaks MCP over stdio. Connect it from any MCP client (e.g. Claude Desktop, opencode) using:
{
"mcpServers": {
"osmos-marketing": {
"command": "node",
"args": ["/absolute/path/to/api_mcp/server.mjs"]
}
}
}Auth
Every API call requires both headers — they are passed as x_token and x_retailer_id tool arguments:
x-token: Authentication token
x-retailer-id: Retailer identifierWithout both, the tool returns a clear error explaining they are required.
Adding a new endpoint
Add
registry/endpoints/<endpoint-id>.jsonfollowing the existing schema pattern (fields:endpoint.id,method,path,operationId,summary,description,parameters,requestBody,responses,deprecated).Add an entry to
registry/endpoints/index.json.Restart the server — the new endpoint tool is registered automatically.
Available Tools
18 toolscreate_spa_campaignB
Create a new Sponsored Products Advertising (SPA) campaign. Creates a new SPA campaign with specified budget settings, bidding strategy, and campaign type. Supports AVERAGE_DAILY_BUDGET (default) and LIFETIME_BUDGET types.
Inputs: advertiser_id (required), body, x_token, x_retailer_id.
create_update_category_bids_for_campaignB
Create or update category bids for a campaign. Creates or updates the category bid settings for a campaign. When mode=MANUAL, the category_bids array is required. When mode=AUTO, the category_bids array is forbidden.
Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.
create_update_negative_keyword_settings_for_campaignA
Create or update negative keyword settings for a campaign. Creates or updates negative keyword settings for a campaign. Each keyword entry is either a create (no id) or an update (id and status required; keyword, match_type, and bid_value forbidden). BROAD match type is not allowed for negative keyw
Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.
create_update_positive_keyword_settings_for_campaignB
Create or update positive keyword settings for a campaign. Creates or updates positive keyword settings for a campaign. Each keyword entry is either a create (no id) or an update (id required; keyword and match_type forbidden). To update a keyword, first fetch keywords via GET to obtain the keyword
Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.
create_update_product_set_for_campaignC
Create or update the product set for a campaign. Creates or updates the product set for a campaign. When products are selected within product sets, each product will function as an individual product ad. Supports AUTO mode (backend auto-selects products) and MANUAL mode (explicit product list).
Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.
get_campaign_forecastA
Get forecast for a campaign. Returns the forecast for a campaign based on its current or overridden budget. Forecasting is not supported for LIFETIME_BUDGET campaigns.
Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.
get_campaign_network_settingsB
Get the networks a Sponsored Products campaign targets. Returns the networks a Sponsored Products campaign targets. A network is a retailer serving surface, such as a country-specific site or a storefront of the same retailer. A campaign with no saved network settings returns an empty networks array
Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.
get_category_bids_for_campaignA
Retrieve the category bids for a campaign. Returns the list of category bids for a campaign, including spend, revenue, ROI, current bid value, and allowed/recommended bid ranges.
Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.
get_endpoint_definitionA
Get the full OpenAPI-derived definition for a specific endpoint by id (request/response schemas, params, examples).
Inputs: endpointId (required).
get_negative_keyword_settings_for_campaignA
Retrieve the negative keyword settings for a campaign. Returns the list of negative keywords for a campaign. Use this endpoint to fetch negative keyword ids before updating their status.
Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.
get_positive_keyword_settings_for_campaignA
Retrieve the positive keyword settings for a campaign. Returns the list of positive keywords for a campaign. Use this endpoint to fetch keyword ids before updating keyword bids or status.
Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.
get_product_set_for_campaignA
Retrieve the product set for a campaign. Returns the product set configured for a campaign. Response is either a MANUAL product set (with explicit product list) or an AUTO product set.
Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.
get_service_detailsA
Get the OSMOS Marketing API service definition including base URL, authentication requirements, and campaign hierarchy.
Inputs: no named parameters.
get_spa_campaign_by_idA
Retrieve a specific SPA campaign by its ID. Returns the campaign details including budget settings, bidding strategy, dates, and status.
Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.
list_endpointsA
List all available API endpoints in the OSMOS Marketing API registry with their methods and paths.
Inputs: no named parameters.
list_spa_campaignsA
List all SPA campaigns for an advertiser with pagination and optional status filter. Returns a paginated list of campaigns. Supports filtering by status (ACTIVE, PAUSED). Offset and limit are required for pagination.
Inputs: limit (required), offset (required), advertiser_id (required), body, +3 more.
save_campaign_network_settingsA
Save the networks a Sponsored Products campaign targets. Saves the networks a Sponsored Products campaign targets. Each call replaces the previously saved set; include every network the campaign should target. A campaign_id that does not exist for the advertiser returns 404 with code RESOURCE_NOT_FO
Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.
update_spa_campaignA
Update an existing SPA campaign. All fields are optional — send only the fields you want to change. To change the campaign's bidding strategy, send bidding_strategy.type. Switches are only allowed within the same bid-mode family — CPC family: MANUAL_CPC, MAX_PERFORMANCE_CPC, ROAS; CPM family: MANUAL
Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool targets a distinct resource and action, from API introspection to campaign and sub-resource management. Even the create_update tools are clearly separated by resource type (product set, keywords, category bids).
Most tools follow a consistent verb_noun pattern (create_, list_, get_, update_), but 'save_campaign_network_settings' breaks the pattern by using 'save' instead of 'create_update'. The combined 'create_update' verbs are somewhat unusual but applied consistently.
At 18 tools, the server is within the 16-25 range that feels heavy per calibration. Each tool covers a specific endpoint, but the count is on the higher end for an MCP server.
The tool set covers the campaign lifecycle and all major sub-entities (product sets, keywords, bids, networks, forecast) well. However, there is no delete_campaign tool, which is a notable gap for a CRUD-like surface.
Related MCP Connectors
Discover, plan and run tools across your connected business systems through one OAuth MCP endpoint
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
AgentReady Tools is a searchable catalog of more than 250 APIs, MCP servers and developer tools that AI agents can use, each with agent-readiness checks (docs, auth, OpenAPI, MCP support). Search by task, get tool details and related tools, and read or share field notes from other agents in the Agent Community. Remote MCP endpoint: https://agentready-tools.com/mcp
Discover and call 10,000+ production APIs from one MCP server. Pay-per-call billing for AI agents.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides 35 MCP tools for automated marketing campaigns, integrating event management, booking, and email marketing into a deterministic pipeline for AI agents.-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to access a unified catalog of tools from various APIs (OpenAPI, GraphQL, MCP, Google Discovery) through the MCP protocol.12 npmMIT
- AlicenseAqualityDmaintenanceExposes OpenAPI/Swagger API documentation as MCP tools, enabling AI agents to search, inspect, and call API endpoints through natural language.55 npmMIT
- AlicenseAqualityCmaintenanceEnables AI agents to perform go-to-market workflows such as company and contact enrichment, CRM querying, and controlled, audited writes to a CRM through MCP tools callable from any MCP client.1MIT