Connect an external system
Connectors give agents read access to the org's third-party systems, grouped by domain: commerce (orders + product catalog — Shopify, Magento 2), bookings (Gastroplanner) and seo (search performance — Bing Webmaster Tools, Google Search Console). Admin agents use the lookup tools while handling a support conversation; customers' own agents get the self-service tools (commerce_list_my_orders, bookings_list_my_bookings), scoped server-side to their own records. Not every domain has that second half — seo is operator-facing only, because no customer asks about impressions or average position.
For a system no vendor adapter covers — a proprietary CRM, a subscription database — the org can host its own MCP server and connect it with the custom-mcp vendor instead: see skill://connectors/connect-custom-mcp-server.
connectors_list_vendors returns the supported systems and the exact config fields each one needs.
TL;DR
- Have the human create a read-only API credential in the external system (per-vendor steps below).
connectors_create_connectionwithvendor, aname, and the vendor's non-secret config fields. The vendor determines the domain. The response includes a one-time credential link.- Share the credential link — the human opens it and enters the secret directly in the dashboard. The link expires after 24 hours and closes once the secret passes the connection test; until then the human can re-test or re-enter on the same page. Mint a fresh one with
connectors_request_credentialsif it lapses. connectors_test_connection— verifies the stored credential with a read-only probe.- Mint delegated end-user tokens with
commerce:readand/orbookings:readto enable customer self-service.
Never ask for a secret in the conversation and never put one in config — the tool rejects secret fields. Secrets only enter through the credential link, are encrypted at rest, and are never returned by any tool. Munin only ever needs read access — never grant write scopes in the external system.
Shopify (commerce)
Create a custom app token in the Shopify admin:
- Shopify admin → Settings → Apps and sales channels → Develop apps → Create an app.
- Under Configuration → Admin API integration, grant exactly three scopes:
read_orders,read_customers, andread_products. - Install the app and copy the Admin API access token (
shpat_…). Shopify shows it once.
{
"vendor": "shopify",
"name": "Main store",
"config": {
"shopDomain": "your-store.myshopify.com"
}
}
The credential link asks for the Admin API access token. shopDomain is the permanent *.myshopify.com domain, not your custom storefront domain, and is required at create time. apiVersion is optional (defaults to a current stable version).
Note: apps with read_orders see the last 60 days of orders by default; request the read_all_orders scope in the Shopify app config if customers ask about older orders. A connection created before product lookups existed needs read_products added in the Shopify app config — no change in Munin, the stored token picks up the new scope.
Magento 2 / Adobe Commerce (commerce)
Create an integration token:
- Magento admin → System → Extensions → Integrations → Add New Integration.
- Under API, grant resource access to Sales (read), Customers (read), and Catalog (read) only. Include CatalogInventory if you want product lookups to report stock availability — without it, availability comes back as unknown rather than failing.
- Save, Activate, and copy the Access Token.
{
"vendor": "magento",
"name": "EU storefront",
"config": {
"baseUrl": "https://store.example.com"
}
}
The credential link asks for the access token. baseUrl must be https and publicly reachable (private/internal hosts are refused). Shipment tracking comes from the Sales → Shipments resource, so include it in the ACL.
Product links
Product cards in the chat widget link to the product's page on the storefront. By default that link is Magento's own product route on the store view's base URL (…/catalog/product/view/id/<id>), which works on any standard Magento frontend. When customers shop on a different host than baseUrl — a headless or PWA storefront — or you want the pretty URL, set productUrlTemplate to the storefront's product URL with a placeholder:
{
"vendor": "magento",
"name": "EU storefront",
"config": {
"baseUrl": "https://admin.store.example.com",
"productUrlTemplate": "https://store.example.com/products/{urlKey}"
}
}
The placeholders are {urlKey} (the product's URL key in the connection's store view), {sku} and {id}. A standard Magento frontend's pretty URL is usually https://store.example.com/{urlKey}.html. A product with no URL key, or one set to Not Visible Individually, gets no link. The template can be added to an existing connection with connectors_update_connection.
One Magento install, several sites
When one Magento install runs several sites (Magento websites), create one connection per site and set storeCode to a store view code of that site:
{
"vendor": "magento",
"name": "Acme store",
"config": {
"baseUrl": "https://store.example.com",
"storeCode": "acme"
}
}
With a storeCode, every call goes to /rest/<storeCode>/V1, so product names and prices come from that store view. Order lookups only return orders placed in a store view of the same website, and product search and lookups only return products assigned to that website. Without it the connection sees every website, as before. connectors_test_connection fails if the code doesn't exist, and the error lists the store view codes that do. The access token can be shared between the connections: create each one with its own credential link and paste the same token.
Pin each connection to the chat widget or channel of its site so the support agent never queries the wrong store — see skill://conv/serve-multiple-sites.
Gastroplanner (bookings)
Gastroplanner's customer API (https://api.gastroplanner.eu/docs/customer/) uses a Bearer token plus an X-RESTAURANT header naming the restaurant every query runs against:
- Request an API token from Gastroplanner support for your account.
- Create the connection with the restaurant URI (the
X-RESTAURANTvalue for your venue) — the credential link asks for the API token.baseUrlis only needed for a non-standard endpoint.
{
"vendor": "gastroplanner",
"name": "Restaurant bookings",
"config": {
"restaurantUri": "my-restaurant"
}
}
Run connectors_test_connection after creating it — the probe lists the restaurants the token can access and fails with the available URIs if restaurantUri doesn't match one. Note: Gastroplanner bookings have no confirmation code; guests identify a booking by the bookingRef from a listing.
Vendors that authorize by redirect
Most vendors above are a pasted key: the human opens the credential link and enters a token. A vendor that authorizes by OAuth instead — Google Search Console today — needs one extra step, and connectors_list_vendors marks which ones those are.
The org registers its own OAuth client (Google Cloud console → APIs & Services → Credentials → OAuth client ID, type "Web application"), with Munin's callback as an authorized redirect URI. The client id and secret are per-connection config, not deployment settings, so a self-hoster uses their own client rather than Munin's.
{
"vendor": "google_search_console",
"name": "Main site",
"config": {
"clientId": "000000000000-xxxxxxxx.apps.googleusercontent.com"
}
}
clientSecret is a secret field, so it goes through the credential link like any other — never in config.
Then hand the human the authorization link:
{ "name": "connectors_get_authorize_url", "arguments": { "connectionId": "<connectionId>" } }
They open it in a browser and approve the Google account that owns the Search Console property. The callback exchanges the code and stores the grant.
Three things worth knowing:
- The link is short-lived — it expires after 10 minutes. Call the tool again for a fresh one rather than re-sending an old link.
- The connection stays
pendinguntil the grant lands, even once the client secret is stored, because a client secret alone cannot call the vendor.credentialStatereadsactiveonly after the redirect completes. credentialState: "expired"means the grant was revoked or lapsed — the fix is the same call: mint a new authorization link and have the human approve it again. Tokens refresh themselves in the background otherwise.
Finish with connectors_test_connection as usual, then seo_list_properties to confirm the account's verified sites are visible — see skill://seo/improve-search-performance.
Google's webmasters.readonly is a sensitive scope. An org's own OAuth client works unverified against accounts that org owns, which covers the normal case. Distributing one client to other people's accounts is what triggers Google's app-verification process (CASA assessment, privacy policy, demo video) — worth knowing before promising a customer a one-click connect.
Multiple connections
Connections are org-scoped and names must be unique. Within a domain: with one active connection, lookup tools use it automatically; with several, calls must pass connectionId (the error message lists the candidates). A channel can pin its own commerce and bookings connection with conv_set_channel_sources; in that channel's conversations the support agent always uses the pinned connection and any other connectionId is refused (skill://conv/serve-multiple-sites). A pinned connection can't be deleted until it is removed from those channels. Connections in different domains never conflict — a Shopify store and a Gastroplanner account coexist without any connectionId. Deactivate with connectors_update_connection { active: false } to take one out of rotation without deleting the credential.
connectors_update_connection handles renames, non-secret config changes, and activation — the stored secret is kept, and secret fields are rejected the same way as at create time. To rotate a credential, delete the connection and create it again, entering the new secret through the fresh credential link (or use the dashboard's Integrations page).
The stored secret only goes to the host it was entered for. An update that moves the connection to a different host — a new custom MCP url, Magento or Gastroplanner baseUrl, or Shopify shopDomain — is refused with connectors_secret_required unless the secret is supplied in the same change. Changes on the same host, such as a different path, keep the secret. To move a connection, either have a person edit it on the dashboard's Integrations page, where the secret field becomes required once the address changes, or delete the connection and create it again with the new address and a fresh credential link. Never ask for the secret in the conversation to get around this.
The identity model — read before enabling self-service
Self-service lookups trust the email on the end-user record, and end-user records are created by your backend when it mints delegated tokens (POST /v1/tokens/delegated). The chain is:
your app authenticates the customer → mints a delegated token with their email
→ the self-service tool resolves that email server-side → vendor returns only that customer's records
Two rules follow:
- Only mint delegated tokens with emails your system has actually authenticated (login session, verified email link). If you mint tokens from unauthenticated visitor input, you are asserting an identity you haven't checked, and that visitor's agent can read that email's order and booking history.
- End-user records without an email can't look up anything — the tools refuse rather than guess.
- Munin trusts an email only when it knows where it came from: your backend attested it (a delegated mint, a signed widget or
identifyemail, or/v1/end-users), or it arrived as the sender of an inbound email or channel webhook. An email a visitor typed in chat, or one written by any path that doesn't record its source, is refused for personal lookups. - An email a visitor typed in chat is never upgraded by a mint. Minting by email alone skips any end user whose email was self-reported and binds the email to a fresh end user instead, releasing the visitor's unverified claim on it; minting for a named end user replaces a self-reported email rather than refusing.
Pass email when you mint
Pass the customer's email in the mint request and Munin binds it to the end user and records it on the token as attested (attestedEmail in the response). That keeps the address on file the one your login actually checked, rather than one that arrived some other way. The attestation has to agree with the record:
- If the end user already carries a different email, the mint fails with
delegated_email_mismatch(400). - If the end user has no email and another end user in the org already holds this one, the mint fails with
delegated_email_conflict(409); mint for that end user instead. - A mint that names only
emailreuses the end user already holding that address.
Inbound email and SMS are not authenticated identity
The self-service tools refuse an address a visitor merely typed into the chat widget. They do not refuse an address that arrived as an email From: header or an SMS sender number — and those are spoofable. Anyone can send mail claiming to be jane@example.com; sender and caller ID are forgeable too. Munin parses the receiving server's Authentication-Results header on inbound mail and records a DMARC verdict on each message. The self-service tools that touch personal records — order and booking reads and writes, and crm_get_my_contact / crm_update_my_contact — act on it, but only on an explicit failure: they refuse when the latest message failed DMARC for its From address, and when the latest message was forwarded, because the original sender's address then comes from the forwarded text rather than from anything a mail server checked. A DMARC failure on the forwarding message itself still counts as a failure. Reads are refused too, not just writes: the reply goes to the real owner of the address, but a forged message can ask for the answer to be embedded where it leaves the mailbox, so the record must not be fetched in the first place. Mail with no DMARC result is still treated as coming from the address in its From line. DMARC proves the sending domain, not the mailbox, so anyone who can legitimately send from the same domain passes it.
In practice that is the same trust level every support desk operates at when a human reads an inbound email and looks up the order — order status is low-harm, and the alternative (challenge every customer) makes the product useless. Know the trade-off rather than assume the tools verified something:
- Fine over email/SMS: order status, delivery ETA, booking times — the postcard test.
- Not fine over email/SMS without your own step-up: anything whose disclosure to the wrong person causes real harm, and any action that costs money. Route those to a human, or have your own system verify with a one-time link or code first.
- Booking changes through the self-service tools are allowed over email and voice by design, since a table or appointment is low-harm; Munin refuses them only when the message explicitly failed DMARC or names its sender only inside forwarded text.
- An email the agent sends without a person approving it only embeds images hosted by this Munin deployment (its API and asset storage). An image from any other host is reduced to its alt text, so an auto-reply can't load a URL that carries data to a third party. Replies a teammate writes or sends from a draft in the dashboard, and outreach a person approved, keep images from any https host.
- Want a strong identity on the widget? Use the identity-verification secret or a delegated token — those are the only paths Munin treats as authenticated. Sign the email into the widget hash too (
skill://conv/setup-chat-widget, Signing the email too) so a signed-in widget user's email counts as theirs rather than as typed by the visitor.
A connected custom MCP server is told which of these it is dealing with on every call; see skill://connectors/connect-custom-mcp-server.
The end-user can never choose which email to query: the self-service tools take no email parameter. Admin lookup tools (commerce_list_customer_orders, bookings_list_guest_bookings) can query any email — that surface is for your own support staff and is never exposed to delegated tokens.