Developer documentation

MCP server

The MCP server lets an AI assistant work in your Iteras account. Your staff can ask it to find a customer, explain why a subscription stopped or pause the deliveries for a vacation, and the assistant does it with the tools listed below. The tools call the endpoints described in the rest of this documentation, so the same rules and checks apply.

The server speaks the Model Context Protocol (MCP) over Streamable HTTP. Assistants connect with OAuth, so each person signs in with their own Iteras login. Developer tools can connect with an API key instead.

Connecting an assistant

Add Iteras to the assistant as a custom connector or MCP server with this URL, and choose OAuth if the assistant asks how to sign in:

https://app.iteras.dk/api/mcp

The assistant then sends you to Iteras, where you log in as usual and choose:

  • The account the assistant works in. It works as you, so you can only choose the accounts you have access to.

  • Whether it may only read data, or read and change data. Only users with the access right "Basic system setup" or "Developer relevant setup" can let an assistant change data.

Apps on your own computer can connect the same way. Iteras shows a warning for them, since any app on the computer could start the sign-in.

The connection then appears under your profile in Iteras and under API accesses, with the date it expires. After that date, the assistant asks you to connect again. You can remove the connection in either place to disconnect the assistant at once. It also stops working when your password changes or your user leaves the account, and a connection that may change data stops when you lose the access rights to allow that.

The connection's key only works through the MCP endpoint, which never hands customers' passwords, login codes or login links to the assistant. To call the rest of the API directly, create an API access of its own.

Connecting with an API key

Developer and automation tools can send an API key instead of signing in. Create an API access that allows "AI assistants (MCP)", plus the APIs the tools should be able to use, and send its key as a bearer token:

POST /api/mcp HTTP/1.1
Host: app.iteras.dk
Authorization: Bearer <Iteras API key>

The server only reads the key from the Authorization header. A key that does not allow "AI assistants (MCP)" is refused, so the keys of your existing integrations can't be used by an assistant unless you allow it. IP restrictions on the key apply as for other API calls.

The tools

The assistant sees all the tools, whatever the connection allows. A tool the connection may not use answers with an error that names the API it needs, so the assistant can tell you what is missing. Like the rest of the API, the tools take and return IDs as strings, and take amounts in cents.

A tool takes the parameters of the endpoint it calls under the same names, so the page of the endpoint describes them, but not all of them: e.g. the tools leave out what is only for imports. The customer's ID is id in get_customer and in the tools that change a customer, customer in list_events, list_orders and create_payment_url, and price_calculated_for_customer in list_campaigns, as in the API. A list is returned a page at a time, and its next_cursor gives the next page.

Tool Description Needs the API
check_distribution_coverage Tells whether the distribution integrations set up on the account deliver to a given address. More: read_documentation("server/distributioncoverage"). Distribution coverage
describe_fields Lists the fields of the account, built-in and custom, with ID, name, type, choices and the condition operators each can be filtered with; `condition_operator_parameters` says which parameters each operator takes. `used_for` says what a field belongs to. Use the IDs in data, new_values and search filters. A field with very many choices lists only the first; give one of the others by its identifier or name as the user knows it. More: read_documentation("server/fielddefinitions"). Field definitions
get_account_context Call this first. Returns the Iteras account you act in: its name, language, timezone and current local time, whether it is a test account, its own words for customer and subscription (the user may use them, the tools always say customer and subscription), how many customers and subscriptions with an active period it has, its business entities with currencies and online payment methods, its subscription products, and what this connection may and may not do.
get_customer Returns one customer: their data, subscriptions with current period, price, payment agreement and the complaints allowed, products, balance, overrides (pauses, address changes) and complaints. The balance is paid minus invoiced, so a negative amount is what the customer owes. Ask for invoices, payments or estimated invoicings only when needed. More: read_documentation("server/retrievingcustomers"). Retrieve subscriber data
get_distribution_days Lists the information defined in Iteras for specific distribution days, such as which days a physical product is distributed. More: read_documentation("server/distributiondays"). Distribution days
list_campaigns Lists the campaigns customers can subscribe on, with their periods, prices and products. campaign_id is the ID used when creating or switching subscriptions. More: read_documentation("server/campaigns"). Retrieve campaign data
list_events Lists the events in the history of the account: changes to customers and subscriptions, invoices, payments and more. Narrow it down with customer, types and dates. To keep another system up to date, see read_documentation("guides/synchronization"). More: read_documentation("server/events"). Retrieve event data
list_orders Lists orders placed through the ordering forms, newest first. More: read_documentation("server/orders"). Retrieve order data
list_policies Lists the business policies of the account: the settings for invoicing, payment, cancellation terms and self-service that campaigns and subscriptions use. More: read_documentation("server/policies"). Retrieve business policy data
read_documentation Reads a page of the Iteras documentation as markdown, with the fields of this account in its examples: everything about an endpoint behind a tool, what it returns and its errors, or the concepts and guides around them, e.g. server/conditionsformat for search filters.
search_customers Finds customers with a conditions filter: by free text as in the search in Iteras with a customer:freetextsearch condition, by their fields, by their subscriptions and more. Returns their data and active subscriptions, by customer ID. For everything about one customer use get_customer, and for the number of customers get_account_context. More: read_documentation("server/retrievingcustomers"). Retrieve subscriber data
assign_product Assigns a product to a customer or one of their subscriptions, e.g. a gift or a book. A product sold on its own is invoiced right away. More: read_documentation("server/assignproduct"). Change subscriber data
cancel_product_assignment Cancels a product assignment, optionally crediting an amount. More: read_documentation("server/cancelproductassignment"). Change subscriber data
cancel_subscription Stops a subscription now or at a later time. Anything invoiced for the time after the stop is credited. The customer is not sent a cancellation email. More: read_documentation("server/cancelsubscription"). Change subscriber data
create_customer Creates a customer and returns its ID. Add subscriptions with create_subscription afterwards. Check with search_customers first that the customer does not exist already. To import many customers, see read_documentation("guides/migrations"). More: read_documentation("server/createcustomer"). Change subscriber data
create_override Creates an override on a customer or one of their subscriptions: a pause of the subscription or its deliveries for a period, delivery to another address for a period, or a change of the delivery address, billing address or fields at a future date. Pauses can change what the customer is invoiced. Email addresses cannot be changed. More: read_documentation("server/createoverride"). Change subscriber data
create_payment_url Creates a URL where a customer pays an invoice, creates a new payment agreement or replaces an existing one through a payment gateway. Send it to the customer; it opens the payment provider and returns to self-service afterwards. A business entity without a self-service has nowhere to return to, so tell the user to make the link in Iteras. More: read_documentation("server/createpaymenturl"). Create payment URL
create_subscription Creates a subscription for a customer on a campaign. It is invoiced and renewed by the campaign and its business policy, so the customer can be sent an invoice. More: read_documentation("server/createsubscription"). Change subscriber data
delete_override Deletes an override that has not taken effect yet, i.e. a future change or a vacation that has not started. To end one that has, give it an earlier end with update_override. More: read_documentation("server/deleteoverride"). Change subscriber data
register_complaint Registers a delivery complaint on a subscription, e.g. a missing paper. The customer may be compensated. The dates and reason codes allowed are in get_customer: subscriptions[].allowed_complaint_dates and allowed_complaint_reason_codes. More: read_documentation("server/registercomplaint"). Change subscriber data
restart_subscription Restarts a stopped subscription, or takes back a stop set for the future. The customer may be invoiced. More: read_documentation("server/restartsubscription"). Change subscriber data
switch_subscription_plan Switches a subscription to another campaign of the same business entity, immediately: the ongoing period is stopped and a successor is created with the new campaign, credited and re-invoiced as needed. More: read_documentation("server/switchsubscriptionplan"). Change subscriber data
update_customer Changes the attributes of a customer; those not given are left unchanged. Email addresses cannot be changed by an assistant. An address change applies at once and for good; a temporary or later move is an override, see create_override. More: read_documentation("server/updatecustomer"). Change subscriber data
update_override Changes an existing override, e.g. a new end to extend or shorten it, or a new address. It is also how a suspension is ended, which unpauses the subscription. The override ID is in get_customer: overrides[].override_id. Email addresses cannot be changed. More: read_documentation("server/updateoverride"). Change subscriber data
update_product_assignment Changes the custom fields of a product assignment. More: read_documentation("server/updateproductassignment"). Change subscriber data
update_subscription Changes the custom fields or the business policy of a subscription. More: read_documentation("server/updatesubscription"). Change subscriber data

What an assistant cannot do

Some operations are left out because they are hard to undo or affect many customers at once: deleting customers, bulk updates, creating, changing and deleting campaigns, invoicing, registering payments and placing orders. Use the API directly or Iteras itself for those. A connection can make up to 50 changes an hour; to change many customers at once, use an automation.

An assistant cannot change the email address or the password of a customer, since that is what the customer logs in to self-service with: the tools don't take them, and for a connection made by signing in, the API refuses them too. It cannot generate one-time passwords or check passwords. Password hashes, self-service login links, invoice links, one-time passwords and password reset links are left out of everything the tools return.

Keeping track of assistants

A change made by an assistant is recorded in the history like any other change through the API, as made by the assistant for the person who connected it, e.g. "Claude (you@example.com)". Webhooks and the other integrations are notified as usual.

Note that everything the tools return is visible to the assistant and its provider, the same as anything else shared in a conversation, and that includes customer data. Make sure your agreement with the provider covers it.