> For the complete documentation index, see [llms.txt](https://help.theaffiliateplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.theaffiliateplatform.com/apis-and-configurations/mcp-server.md). # MCP Server The **MCP Server** connects an AI assistant (Claude, ChatGPT, Cursor and others) or your own script to your TAP account. The assistant can read your affiliates, deals, brands and destination links, and analyse the numbers of the Media report. It only reads: nothing in TAP can be changed through it. This page has two parts. [For the operator](#for-the-operator): who can use MCP and how the two kinds of access differ. [Technical reference](#technical-reference): the tools and the data each one can read. ## For the operator ### Who can use it | Role on the TAP account | Can use MCP | | ------------------------ | ---------------------------------------- | | Affiliate Admin | Yes | | Affiliate Manager | No | | Affiliate Admin, Limited | No | | Affiliates | No. The affiliate portal cannot connect. | Before a person can connect, check these three things: 1. **MCP is switched on for your TAP account.** Smartico switches it on. Ask your account manager. 2. **The person is Affiliate Admin on the account.** Roles are set per account. A person who is Affiliate Admin on account A and Affiliate Manager on account B can use MCP on account A only. 3. **The person has an MCP access profile.** A new user starts on **MCP No Access**, and with it every connection is refused. Ask your Smartico account manager to set the profile. The profile decides which tools the assistant gets: see [Access profiles](#access-profiles). Affiliate Admins manage MCP under **Label → MCP**: **Access tokens**, **Access profiles**, **Playground** and **Usage**. Every call the assistants make is listed under **Usage**. If the MCP menu is missing, ask your account manager. ### Two kinds of access There are two ways to connect. Both read the same data and follow the same rules. They differ in who they belong to. | | Personal access (Sign in with Smartico) | Service token | | ------------------------ | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | For | A person who connects their own AI assistant: Claude, ChatGPT, Cursor, Windsurf or Gemini | Scripts, servers, your own AI agents, and clients that cannot sign in, such as Claude Code | | How it is made | The person adds the MCP address to their assistant and signs in with their back-office account | An Affiliate Admin creates it under **Label → MCP → Access tokens** and copies it. The full token is shown only once. | | Acts as | That person | The AI/API user of the account where it was made, with the rights of an Affiliate Admin | | Access profile | The person's own profile | The profile chosen on the token | | TAP accounts it covers | The accounts the person chooses at sign-in, where they are Affiliate Admin | The accounts chosen on the token. The person who creates it must be Affiliate Admin on each of them. | | Stops working when | The person's user is deactivated, or they are no longer Affiliate Admin on the account | It is deactivated on the **Access tokens** screen, or the person who created it is no longer Affiliate Admin on the account | | AI tokens are counted on | The person's home label | The home label of the person who created it | Choose **Sign in with Smartico** for people: there is nothing to copy or store, and each person works with their own rights. When an administrator changes a person's profile, the person signs in again. Keep a service token like a password: anyone who has it can read the account with the token's profile. Make one token per script, with a clear name, so you can stop each one on its own. To stop a token, deactivate it on the **Access tokens** screen. ### Connect The MCP address is `https://aichat-api.smartico.ai/mcp`, where `` is the number of your environment. Ask your account manager for it. The steps for each AI assistant are on [MCP - Connect Claude, ChatGPT, Cursor and other MCP Clients](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-connect-claude-chatgpt-cursor-and-other-mcp-clients). If your account uses an IP allowlist for the back office, it applies to MCP too. ### Access profiles The access profile decides which tools a connection gets. On a TAP account the built-in profiles give this: | Profile | What the assistant can read on a TAP account | | ------------------------------------ | ---------------------------------------------------------------------------- | | **MCP Full access**, **MCP Analyst** | Affiliates, deals, brands and destination links, and the affiliate analytics | | **MCP Editor**, **MCP Viewer** | Affiliates, deals, brands and destination links. No affiliate analytics. | | **MCP No Access** | Nothing: the connection is refused | In a custom profile, the affiliate analytics come with the **Data warehouse** group of tools. More about profiles: [MCP - Access Profiles](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-access-profiles). ## Technical reference ### Affiliates, deals, brands and destination links Five entity types can be read on a TAP account. The assistant finds them with `entity_types_list`, reads the fields and filters of one type with `entity_describe`, searches with `entity_list`, and reads whole records with `entity_get` (one record) or `entity_get_many` (up to 20). | Type | What it holds | Filters | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `affiliate` | Name, login, e-mail, company, country, status, manager, parent affiliate, the brands it may promote, its current default deal, your affiliate tags, and its lifetime commissions, payments, adjustments and balance | Affiliate ids, search text, status, manager, parent affiliate, brand | | `affiliate_deal` | The commission terms of one affiliate: type (CPA, CPL, RevShare or a mix), amounts, qualification rules, tiers, the players it applies to, and every version of the deal | Affiliate, deal type, deal, current version, default deal | | `affiliate_sub_deal` | What a parent affiliate earns from its sub-affiliates: CPA fee and commission cut for each level of the network | Affiliate, current version | | `affiliate_brand` | Name, description, active or not, custom domain, the linked Smartico label, the number of destination links, and the visits and registrations of the last 7 days | Search text, active, Smartico label | | `affiliate_link` | Name, brand, link type, destination URL and its A/B variant, blocked countries, public or private, the affiliate tracking link, your link tags | Affiliate (the links this affiliate sees in their portal), search text, brand, link type, enabled, public, default | Some data is kept out on purpose: API keys, payment details (IBAN, wallets), phone numbers and messengers, login IP addresses, and the admin fee. Promo codes, media assets, pixels and payment requests cannot be read over MCP. The lifetime totals on an affiliate record are running totals and can differ a little from the reports. For a number you report, use the affiliate analytics below. Example: the approved affiliates of one manager. ```json { "entity_type": "affiliate", "filters": { "aff_status_id": 2, "manager_id": 1234 }, "limit": 20 } ``` ### Affiliate analytics The affiliate analytics are the numbers of the Media report: visits, registrations, FTDs, deposits, P\&L, commissions, payments and balance, by affiliate, brand, link, campaign, deal, country, player and time. The assistant reads them with two tools. #### get\_affiliate\_analytics\_structure Lists the columns the assistant can query, each with its title and meaning, your own tag names, the account currency, the rules and example queries. The assistant reads it once, before its first query. | Parameter | Meaning | | ---------- | ---------------------------------------------------------------------------- | | `label_id` | Optional. The TAP account to read, when the connection covers more than one. | #### exec\_affiliate\_sql Runs one SQL `SELECT` over a table named `DATA` and answers the rows as CSV. `DATA` holds the records of your account only: one row for each visit, registration, day of a player's money, payment, adjustment and sub-affiliate commission. A query that reads anything else is refused. | Parameter | Meaning | | ---------- | ------------------------------------------------------------ | | `sql` | One `SELECT` that reads `DATA` (and your own `WITH` tables). | | `max_rows` | How many rows to answer: 100 by default, up to 1,000. | | `label_id` | Optional. The TAP account to read. | Example: FTDs and net P\&L by affiliate in October. ```json { "sql": "SELECT affiliate_id, affiliate_name, SUM(ftd_count) AS ftds, SUM(net_pl) AS net_pl FROM DATA WHERE __time >= TIMESTAMP '2026-10-01' AND __time < TIMESTAMP '2026-11-01' GROUP BY 1, 2 ORDER BY net_pl DESC", "max_rows": 2 } ``` The answer: ```json { "columns": [ { "name": "affiliate_id", "type": "VARCHAR" }, { "name": "affiliate_name", "type": "VARCHAR" }, { "name": "ftds", "type": "BIGINT" }, { "name": "net_pl", "type": "DOUBLE" } ], "rows_csv": "affiliate_id,affiliate_name,ftds,net_pl\n1201,Casino Reviews Hub,41,18350.5\n1187,Bet Tips Daily,26,9120", "row_count": 2, "truncated": true, "scanned_rows": 87412000, "tokens_used": 8741 } ``` How to read the numbers: * **Measures add up.** Use `SUM` for every measure. A rate is a `SUM` divided by a `SUM`, for example `SUM(ftd_count) / SUM(registration_count)`. * **Time is UTC.** Filter `__time` for a period, and group by month with `TIME_FLOOR(__time, 'P1M')`. A query without a time filter covers the whole history: use it for lifetime totals, such as each affiliate's balance today. * **Names are columns.** `affiliate_name`, `brand_name`, `deal_group_name` and the other names are in `DATA`. Group by the id and its name together. * **Amounts** are in the account currency. `pl` is P\&L, positive when the operator wins. `net_pl` is the base of RevShare. Commissions and balance are what you owe the affiliate. * **Freshness:** registrations, deposits, payments and adjustments are updated every 15 minutes. Visits can come later. Today is not complete. * **AI tokens:** each query uses AI tokens from your organization's monthly allowance (see [AI Assistant](https://help.theaffiliateplatform.com/ai-agents/ai-assistant)). A longer period costs more. The answer shows `tokens_used`. The measures have the names of the [Reporting API](https://help.theaffiliateplatform.com/apis-and-configurations/reporting-api), and the same period gives the same numbers. Two differences: `chargeback_total` is spelled correctly here (the Reporting API answers `chargback_total`), and rates such as the conversion rate are not columns: the query computes them. The columns of `DATA`: | Group | Columns | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Time and record type | `__time`, `record_type` (visit, registration, daily\_activity, payment, affiliate\_adjustment, registration\_adjustment, sub\_affiliate\_commission) | | Affiliate | `affiliate_id`, `affiliate_name`, `affiliate_username`, `affiliate_status`, `affiliate_registration_date`, `affiliate_last_login_date`, `manager_id`, `manager_name`, `parent_affiliate_id`, `parent_affiliate_name`, `child_affiliate_id`, `child_affiliate_name`, `affiliate_tag_1` … `affiliate_tag_8` | | Traffic | `brand_id`, `brand_name`, `link_id`, `link_name`, `campaign_id`, `campaign_name`, `source_id`, `media_id`, `media_name`, `media_type`, `visitor_id`, `utm_source`, `utm_medium`, `utm_campaign`, `afp`, `afp1` … `afp9`, `link_tag_1` … `link_tag_3`, `media_tag_1` … `media_tag_3` | | Deal | `deal_root_original_id` (the deal group), `deal_group_name`, `deal_type` | | Player | `registration_id`, `ext_customer_id`, `username`, `country`, `registration_product` | | Measures | `visit_count`, `registration_count`, `ftd_count`, `ftd_total`, `qftd_count`, `qlead_count`, `deposit_count`, `deposit_total`, `withdrawal_count`, `withdrawal_total`, `net_deposits`, `bonus_amount`, `chargeback_total`, `deductions`, `volume`, `operations`, `pl`, `net_pl`, `net_pl_casino`, `net_pl_sport`, `commissions_cpa`, `commissions_cpl`, `commissions_rev_share`, `commissions_rev_share_casino`, `commissions_rev_share_sport`, `sub_commission_from_child`, `commissions_total`, `adjustments`, `registration_adjustments`, `payments`, `balance` | The tag columns carry the tag names you set up in TAP. `get_affiliate_analytics_structure` gives the meaning of every column. ### Other tools * `get_product_knowledge` searches the TAP help center and answers with links to the pages. * `read_resource` reads reference documents. `smartico://labels` lists the accounts your connection can use. * `report_problem` lets the assistant tell Smartico when something does not work. * `batch` sends up to 20 calls in one request. Each call is checked as if it were sent alone. ### TAP accounts and Smartico CRM labels in one connection One connection can cover TAP accounts and Smartico CRM labels together. Each call acts on one account or label: pass `label_id` to choose it. Each tool works only on its own kind. The CRM tools (segments, campaigns, the data warehouse and the others) are refused on a TAP account, and the TAP tools are refused on a CRM label. The Smartico CRM tools are described in [MCP - Tools and entity types](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-tools-and-entity-types). ## Frequently asked questions **Can the assistant change an affiliate, a deal or a payment?** No. On a TAP account MCP only reads. **Can an Affiliate Manager use MCP?** No. Only Affiliate Admins can connect to a TAP account, and only they can create service tokens. **The assistant says MCP is not enabled for the account. What do I do?** Ask your account manager to switch MCP on for the TAP account. MCP works on the TAP account only, never on the label of an affiliate's portal. **Can other companies see our data through MCP?** No. A connection reads only the accounts it was given, and an analytics query reads only the account it runs on. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.theaffiliateplatform.com/apis-and-configurations/mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.