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)

How it works

1. server.mjs loads the registry JSON files at startup.

2. It registers a tool for every endpoint in registry/endpoints/index.json (named by converting id to snake_case, e.g. create-spa-campaign → create_spa_campaign).

3. Each endpoint tool accepts path params, query params, an optional body, plus x_token and x_retailer_id auth headers.

4. Calling a tool performs the real HTTP request against https://apiv2.onlinesales.ai/marketing/v1/advertiser and 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 definition

• osmos://endpoints — endpoint index

Prompt

• campaign-hierarchy — explains the campaign hierarchy before acting

Run

npm install
npm start

The 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 identifier

Without both, the tool returns a clear error explaining they are required.

Adding a new endpoint

1. Add registry/endpoints/<endpoint-id>.json following the existing schema pattern (fields: endpoint.id, method, path, operationId, summary, description, parameters, requestBody, responses, deprecated).

2. Add an entry to registry/endpoints/index.json.

3. Restart the server — the new endpoint tool is registered automatically.