> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/connectors/model-context-protocol-mcp.md).

# Model Context Protocol (MCP)

Connect AI assistants to The Wallet Crew documentation and environment data through Model Context Protocol (MCP).

The Wallet Crew provides Model Context Protocol (MCP) servers for documentation and platform operations. An MCP-compatible AI assistant can use them to retrieve current guidance, investigate tenant data, and support operational analysis.

Each environment has its own operational MCP server. Connect only to the environment relevant to the task.

<details>

<summary><strong>Real-world examples</strong></summary>

* A delivery team asks an AI assistant to explain a documented API workflow.
* A support team validates a tenant configuration before escalating an incident.
* An operations team reconstructs a pass lifecycle or checks a scheduled automation.
* A project team drafts a new theme or benefit template in QA and reviews it before rolling it out.

</details>

## Choose an MCP server

Use the documentation server for product guidance. Use an environment server for tenant-specific operational data.

### Documentation MCP

The documentation MCP provides access to The Wallet Crew documentation. It does not require authentication.

**Endpoint:** <https://docs.thewalletcrew.io/~gitbook/mcp>

This server is suited to product questions, implementation guidance, and documentation discovery. It does not expose tenant data.

It needs no sign-in. Connect it first to check that an assistant supports this connection.

### Production MCP

The production MCP provides operational and diagnostic data for production tenants.

**Endpoint:** <https://admin.thewalletcrew.io/api/mcp>

It uses OAuth. Sign in with the same Back-office credentials used for production access.

Authorization metadata is discoverable at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server` on the same host, so a compliant MCP client configures itself from the endpoint URL alone.

{% hint style="warning" %}
Production data can include customer and access information. Use the minimum data required for the investigation. Connect only through approved MCP clients.
{% endhint %}

### QA MCP

The QA MCP provides operational and diagnostic data for QA tenants.

**Endpoint:** <https://admin-qa.thewalletcrew.io/api/mcp>

It uses OAuth. Sign in with the same Back-office credentials used for QA access.

Authorization metadata is discoverable at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server` on the same host, so a compliant MCP client configures itself from the endpoint URL alone.

## Add The Wallet Crew to an AI assistant

Pick an assistant below. In every case, paste the address and sign in with a Back-office account.

| Assistant         | Self-service setup?            |
| ----------------- | ------------------------------ |
| Claude            | Yes                            |
| ChatGPT           | Yes, once developer mode is on |
| Mistral Le Chat   | Yes                            |
| Microsoft Copilot | No — an IT team sets it up     |

Use the address for the required environment.

| Environment                   | Address to paste                            |
| ----------------------------- | ------------------------------------------- |
| Production — real tenant data | <https://admin.thewalletcrew.io/api/mcp>    |
| QA — test data                | <https://admin-qa.thewalletcrew.io/api/mcp> |

Nothing needs installing or downloading. No key, password, or code is needed. The same address is also shown, ready to copy, on the **MCP access** page of the Back-office.

{% hint style="success" %}
The connection is read-only by default. An AI assistant can look things up, and it only sees data already available through the Back-office account. Changes are possible only through the write tools described in [Make changes safely](/connectors/model-context-protocol-mcp.md#make-changes-safely), and each one asks for confirmation before it acts.
{% endhint %}

### Claude

1. Open Claude in a browser or the desktop app.
2. Click the profile picture. Select **Settings**, then **Connectors**.
3. Click **Add**. Then select **Add custom connector**.
4. Paste the required address. Click **Add**.
5. Sign in with the Back-office account. Approve the access request.
6. Leave **Advanced settings** unchanged. The connection is ready.

Claude works on Free, Pro, Max, Team, and Enterprise plans. Free accounts can add one custom connector.

[Get started with custom connectors](https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp)

### ChatGPT

{% hint style="warning" %}
ChatGPT needs a Plus, Pro, Business, Enterprise, or Education account. Use ChatGPT in a web browser. Business, Enterprise, and Education workspaces need an administrator to enable developer mode first.
{% endhint %}

1. Open **Settings**, then **Security and login**. Turn on **Developer mode**.
2. Open **Settings**, then **Connectors**. Click **+**.
3. Name the connection, for example, “The Wallet Crew”. Add a short description.
4. Paste the required address.
5. Select **OAuth** as the sign-in method. Sign in with the Back-office account.
6. Open the connection to see what it can look up.

After a The Wallet Crew release, open the connection and select **Refresh**.

[Developer mode and MCP apps in ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt)

### Mistral Le Chat

1. Open **Connectors** in Le Chat.
2. Click **+ Add Connector**. Select **Custom MCP Connector**.
3. Enter a name without spaces, such as “walletcrew”.
4. Paste the required address in **Server URL**.
5. Click **Connect**. Sign in with the Back-office account when prompted.

[Using MCP connectors with Le Chat](https://help.mistral.ai/en/articles/393511-using-my-mcp-connectors-with-le-chat)

### Microsoft Copilot

Microsoft Copilot does not let an individual add this connection yet. An administrator must set it up for the organisation.

Send the IT team this page and the required address. They can add it through **Add tool → Model Context Protocol** in Copilot Studio.

[Connect your agent to an existing MCP server](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent)

### Other assistants

Other assistants can connect if they support a custom connector by address. Look for **Connectors**, **Custom connector**, or **MCP** in settings. Paste the address, then sign in.

Developer tools, including Claude Code, Cursor, and Visual Studio Code, use the same address. Check their documentation for the setup location.

### Check that it worked

1. Ask: “Which The Wallet Crew tenants can I access?”
2. A tenant list confirms the connection is working.
3. An empty list means the connection works. The account has no access in that environment. Ask a The Wallet Crew administrator for access.

These questions help analyse tenant data:

* “How many passes were installed last month, and how does that compare with the month before?”
* “Which benefit templates are enabled right now, and how many passes hold each one?”
* “Show me the pass with serial number `<PASS_ID>` and what has happened to it.”

### If something goes wrong

| Symptom                                                | What to do                                                                                                                                                                           |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The sign-in window opens and closes without connecting | The assistant may not support this connection. Try a web browser instead of a desktop app. Contact support if it still fails.                                                        |
| It connected, but questions return a permissions error | The Back-office account lacks access to that tenant or data. Ask a The Wallet Crew administrator.                                                                                    |
| One question fails while others work                   | That lookup needs access the account does not have. Ask an administrator to check the role.                                                                                          |
| A change is refused                                    | Writes have not been allowed for the account on that tenant, or the allowed duration has ended. Allow them again from **Settings → Access control → MCP access** in the Back-office. |
| The numbers look wrong or unfamiliar                   | Check the pasted address. QA has test data, not real customer data.                                                                                                                  |
| It stops answering after many questions                | There is a limit on lookups per minute. Wait a moment. Ask again with a narrower question.                                                                                           |

## What the environment MCP can do

The environment MCP acts as a diagnostic and operations control plane. It exposes 51 tools covering tenant orientation, configuration, telemetry, passes and their catalogue, automations, SFTP imports, redirects, access posture, and the REST API reference. Every tool name starts with `twc_`.

Most tools are read-only. Tools that create, change or delete something are marked as write tools in the tables below and follow the confirmation flow described in [Make changes safely](/connectors/model-context-protocol-mcp.md#make-changes-safely).

### Discover tenants and configuration

Every operational session starts by resolving the tenant from the available tenant list. A tenant identifier is never inferred or guessed: a display name or a domain is not a tenant identifier.

| Capability                  | Available tools                                     | Typical outcome                                                                |
| --------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------ |
| List accessible tenants     | `twc_tenants_list`                                  | Resolve the correct tenant before investigation                                |
| Get a tenant overview       | `twc_tenants_get`                                   | Read lifecycle, purpose, languages, custom domain state and enabled extensions |
| Inspect configuration files | `twc_config_files_list`, `twc_config_files_get`     | Find current or historical configuration values                                |
| Audit configuration changes | `twc_config_history_list`, `twc_config_files_diff`  | Identify when, by whom and how a configuration changed                         |
| Validate configuration      | `twc_config_test`                                   | Run the startup validation suite and surface every configuration error         |
| Read configuration schemas  | `twc_config_schemas_list`, `twc_config_schemas_get` | Understand what a configuration file accepts and which properties are required |

`twc_tenants_get` is the one-call orientation for an unfamiliar tenant. A `disabled` status refuses Back-office calls and runs no automation, while holder pages keep working. An `onboarding` status means missing configuration is expected. A `demo` or `test` purpose is not production evidence. A custom domain with `isLive` set to `false` and state `ready` is a pending switch, not a fault.

### Investigate telemetry

Telemetry tools validate runtime behaviour and help identify anomalies. Pass event history is read here, from the `Events` table filtered on `EventData.passId`.

| Capability                  | Available tools           | Typical outcome                                                          |
| --------------------------- | ------------------------- | ------------------------------------------------------------------------ |
| Explore telemetry structure | `twc_insights_schema_get` | List tables, event names and their properties, and runnable KQL examples |
| Query tenant telemetry      | `twc_insights_query`      | Investigate errors, trends, pass histories and unexpected behaviour      |

Every query should be bounded by time and aggregated with `summarize`. User-supplied values are passed as parameters rather than written into the query. Telemetry lags a few minutes behind real time, so a window is widened before concluding that an event did not happen. The tenant filter is added server-side.

### Review passes

A pass is one end-user's wallet card. It is issued from a pass type, shown as "pass template" in the console, and optionally skinned by one theme.

| Capability            | Available tools      | Typical outcome                                                                                |
| --------------------- | -------------------- | ---------------------------------------------------------------------------------------------- |
| Find passes           | `twc_passes_list`    | Filter passes by pass type, theme, one identifier and one metadata condition                   |
| Inspect a pass        | `twc_passes_get`     | Read identifiers, additional data, metadata, per-integration sync state, theme and stamp card  |
| Show a pass           | `twc_passes_preview` | Display the pass as Apple Wallet and Google Wallet draw it, front and back, in every language  |
| Issue a pass (write)  | `twc_passes_create`  | Issue a test pass and get its install link                                                     |
| Update a pass (write) | `twc_passes_update`  | Change pass type, theme or additional data, grant a benefit, and push an optional notification |

`twc_passes_list` returns one page of current store state, without a total. Counts and trends come from `twc_insights_query`. A wrong displayed value usually comes from the pass's `additionalData`.

For a stamp card, `twc_passes_get` returns the current count, target, goal behaviour, state and the last 20 movements. The `stampCard` field is `null` when the pass is not a stamp card.

`twc_passes_preview` draws the pass inside the conversation for clients that support interactive previews, and returns a console link otherwise.

{% hint style="warning" %}
`twc_passes_update` pushes the pass to every device it is installed on at once. The push and its notification cannot be taken back.
{% endhint %}

### Review pass types

Pass types define what a pass looks like and which metadata it carries.

| Capability                 | Available tools                                             | Typical outcome                                                          |
| -------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------ |
| List pass types            | `twc_pass_types_list`                                       | See each pass type with its kind, languages, colours and metadata fields |
| Inspect one pass type      | `twc_pass_types_get`                                        | Read the full configuration, wording per language and stored images      |
| Create or replace (write)  | `twc_pass_types_upsert`                                     | Save a new pass type, or replace an existing one whole                   |
| Manage images (write)      | `twc_pass_types_images_put`, `twc_pass_types_images_delete` | Store, replace or remove an image used by a pass type                    |
| Delete a pass type (write) | `twc_pass_types_delete`                                     | Remove an unused pass type with its wording and images                   |

The pass type `kind` is `customerCard`, `eventTicket`, `giftCard`, `offer`, `generic` or `stampCard`, and cannot change once created. Metadata definitions returned here are the ones `twc_passes_list` filters on. Passes pick up a pass type change on their next update; nothing is pushed. A pass type cannot be deleted while any pass is issued from it.

### Review benefits and benefit templates

A benefit is a redeemable item on a pass, such as a discount, a free product or a gift card balance. It is usually issued from a benefit template, the reusable definition every granted benefit copies. A benefit granted from a template carries the template identifier as `origin.processId`.

| Capability                        | Available tools                                                | Typical outcome                                                                |
| --------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| List benefit templates            | `twc_benefit_templates_list`                                   | Browse the catalogue, disabled templates included                              |
| Inspect a benefit template        | `twc_benefit_templates_get`                                    | Read type, category, validity, code settings, content, images and removal rule |
| Trace issued benefits             | `twc_benefits_list`                                            | List the benefits of one pass, or every pass that received a given template    |
| Create or update (write)          | `twc_benefit_templates_create`, `twc_benefit_templates_update` | Draft a new template, or replace an existing one                               |
| Delete a benefit template (write) | `twc_benefit_templates_delete`                                 | Remove a template that no live benefit or enabled automation depends on        |

A benefit template `type` is `oneTime`, `unlimited` or `multiUse`. A benefit `status` is `scheduled`, `active`, `used`, `expired` or `removed`; `active` means a redemption is accepted now. The `activeOnly` filter of `twc_benefits_list` excludes benefits whose deletion date has passed and does not filter on status.

Updating a benefit template leaves benefits already granted unchanged, unless `refreshGrantedBenefits` is set. A background task then rewrites every live benefit issued from it and pushes each pass carrying one to the end-users' devices. Templates with custom code generation are refused by the write tools.

### Review pass themes

Themes make pass visuals consistent across a tenant.

| Capability               | Available tools                          | Typical outcome                                                                  |
| ------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------- |
| List themes              | `twc_themes_list`                        | See each theme with how many passes currently carry it                           |
| Inspect one theme        | `twc_themes_get`                         | Read colours, localized title and description, and every per-slot image override |
| Create or update (write) | `twc_themes_create`, `twc_themes_update` | Add a theme, or replace one and store its images                                 |
| Delete a theme (write)   | `twc_themes_delete`                      | Remove a theme that no pass carries and no enabled automation applies            |

* A theme is a reusable visual skin with colours and images. It is defined in `server/themes.yml` and referenced by individual passes. A pass has at most one theme.
* Editing a theme restyles every pass carrying it on its next update; nothing is pushed. Read `lastModificationDate` and `passCount` together.
* A theme has no behaviour, validity window, or code. For anything end-users can redeem, review benefit templates and benefits.
* `twc_themes_list` provides the theme identifier used by the `themeId` filter of `twc_passes_list`.
* `mainImageUrl` is the default image. It feeds each platform's banner slot, `appleStrip` and `googleHero`, when no override exists. Apple's other large slots, logos and icon are set only through `images`. Per-language images apply only to Apple Wallet. Google Wallet always serves the default.
* To store images on a new theme, the theme is created first, then updated with `images`.

### Review automations

Automations describe intent. Executions describe outcome. Both are needed when diagnosing "the automation did not run".

| Capability                    | Available tools                                    | Typical outcome                                                               |
| ----------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------- |
| List automations              | `twc_automations_list`                             | See every automation, enabled first, with a plain-English trigger summary     |
| Inspect one automation        | `twc_automations_get`                              | Read the full settings, trigger details and enabled state                     |
| Check whether it actually ran | `twc_automations_executions_list`                  | Confirm success, failure or postponement from telemetry over the last 90 days |
| Discover automation types     | `twc_automations_types_list`                       | See each available type and the settings it accepts                           |
| Create or update (write)      | `twc_automations_create`, `twc_automations_update` | Add an automation, change some of its fields, or pause it                     |
| Delete an automation (write)  | `twc_automations_delete`                           | Stop an automation for good, keeping its execution history                    |

> `twc_automations_list` describes configuration, not outcome. Only `twc_automations_executions_list` shows whether an automation ran. Each row there is a delivery attempt, not a logical run. Several rows can share one `correlationId`. `success = null` means the run was postponed before execution, which is not a failure; `false` means it ran and threw, and is retried automatically; `true` means it completed.

Keeping `enabledOnly` set to `false` when listing automations ensures a disabled automation stays visible. An automation's `actions` are any of `applyBenefitTemplate`, `updateData`, `changePassType`, `applyTheme` and `notify`, applied in that order. Four trigger types exist:

* `recurrence` — a six-field cron expression, seconds first, evaluated in **UTC**, not tenant local time. A schedule firing more often than every five minutes is refused.
* `fixedDate` — fires once at a given instant. A new or changed date must be in the future. In `continuous` mode, it keeps applying to newly matching passes while its monitoring period is open.
* `dateRelative` — fires per pass, offset from a date field on that pass. It can be pinned to a local time in a named timezone.
* `event` — fires per pass on a pass installation, a benefit movement or a metadata change. `firstInstallationOnly` means re-installation does not fire it again.

An enabled automation is live as soon as it is created and acts on every pass it matches. Setting `isEnabled` to `false` stages or pauses it while keeping it.

### Investigate SFTP file imports

SFTP file import is optional. Internally, it is called Triglav. Most tenants do not use it, and a tenant with no inbox is not an error.

| Capability                     | Available tools           | Typical outcome                                                              |
| ------------------------------ | ------------------------- | ---------------------------------------------------------------------------- |
| Check the inbox and list files | `twc_sftp_files_list`     | Confirm the feature is enabled, read an inbox summary and each file's status |
| Explain one import             | `twc_sftp_import_log_get` | Read row counts, refusals and per-pass outcomes, with the failure reason     |
| Inspect raw file content       | `twc_sftp_files_read`     | Page through raw lines to spot delimiter, column or identifier problems      |

* `twc_sftp_files_list` returns `sftpEnabled` set to `false` when the tenant has no SFTP folder, which is the normal case for most tenants.
* File statuses: `pending` means dropped and not yet picked up. `processed` means imported. `error` means processing failed. `twc_sftp_import_log_get` explains why.
* `twc_sftp_import_log_get` separates `noMatchCount`, rows whose identifiers matched no pass, from `refusedCount` and `failedCount`. The first signals data quality, not a pipeline bug. Refused rows name an unknown pass type, theme or benefit template, or a bad identifier.
* `runState` set to `notRecordedYet` means the end of the run has not reached telemetry yet; a new attempt a few minutes later usually answers. Import outcomes are kept for 90 days.
* `twc_sftp_files_read` returns a capped window of lines. The previous result's `nextStartLine` is passed as `startLine` to continue. `nextStartLine` set to `null` marks the end of the file.

{% hint style="warning" %}
SFTP files contain raw customer data, including identifiers, contact details, and transaction rows. `twc_sftp_files_read` requires the separate `tenant.sftp:download` permission, which listing files does not grant. Quote only what the question needs. Do not echo a whole window back.
{% endhint %}

### Audit short URLs

| Capability       | Available tools      | Typical outcome                                                            |
| ---------------- | -------------------- | -------------------------------------------------------------------------- |
| Audit short URLs | `twc_redirects_list` | Find redirects, the layout each one lands on, and their expiration details |

Expired redirects are left out unless `includeExpired` is set. Every visit records a `Redirect:Redirected` event, so click counts come from `twc_insights_query`.

### Review access posture

Security tools return access metadata, never API-key values.

| Capability                       | Available tools                 | Typical outcome                                                                   |
| -------------------------------- | ------------------------------- | --------------------------------------------------------------------------------- |
| Review Back-office users         | `twc_security_users_list`       | Check roles, blocked accounts and last sign-in                                    |
| Review API keys                  | `twc_security_api_keys_list`    | Check permissions and enabled status without exposing secrets                     |
| Review roles and what they grant | `twc_security_roles_list`       | See each role as stored, fully resolved, and the entries that resolve to nothing  |
| Understand a permission scope    | `twc_security_permissions_list` | Turn a scope code into a plain-language meaning, or find the right scope to grant |

To explain a 403, the person's role is found with `twc_security_users_list`. The required scope is then checked against that role's `resolvedScopes`. A scope in `unknownScopes` grants nothing. It is either a typo, because scope spelling is not validated when a role is saved, or belongs to a currently disabled extension. Enabled extensions are confirmed with `twc_tenants_get`. A role with `fullAccess` set to `true` holds `*` and bypasses the scope list, including scopes added by future releases.

`write` never implies `read` anywhere in this platform. A role holding only `tenant.pass:write` can update a pass and cannot look one up.

### Explore the REST API

The REST API reference tools describe the API served by the connected environment. They help an assistant build or debug an integration without leaving the conversation.

| Capability            | Available tools           | Typical outcome                                                               |
| --------------------- | ------------------------- | ----------------------------------------------------------------------------- |
| List API operations   | `twc_api_operations_list` | Find endpoints by tag, path, method or required scope                         |
| Inspect one operation | `twc_api_operations_get`  | Read parameters, request body, responses, required scopes and a curl skeleton |
| Inspect one API model | `twc_api_schemas_get`     | Read a model with every schema it references and the operations that use it   |

The `internal` document covers the full API surface; `v1` covers the public subset.

## Make changes safely

Write tools let an assistant prepare and apply changes, such as issuing a test pass, adjusting a theme or pausing an automation, without switching to the console. They are deliberately gated, because a change in an environment is real for every end-user it touches.

A write runs only when all of these hold:

* The environment exposes write tools. They are listed only where the environment allows writes.
* The tenant allows MCP writes.
* The Back-office account has allowed writes on that tenant, for a limited time, from the **MCP access** page of the Back-office.
* The account holds the permission scope the change requires.

A refused write changes nothing, and the refusal names the Back-office page to open.

### Allow writes in the Back-office

Write approval is personal and deliberately short-lived, so an AI assistant cannot keep changing a tenant long after the task that needed it. It applies to one tenant in one environment, and each write still asks for confirmation and needs the usual permissions.

1. Open the tenant in the Back-office of the required environment.
2. Go to **Settings → Access control → MCP access**, then the **My access** tab. In production, the page is at [admin.thewalletcrew.io/tenant/\~/settings/access/mcp/mine](https://admin.thewalletcrew.io/tenant/~/settings/access/mcp/mine).
3. Check the **Environment** badge next to the page title.
4. In **My write access**, pick a **Duration**, then click **Allow writes**.

<figure><img src="https://3852727835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlP7d71aYydav6e0pRkxc%2Fuploads%2FQUuVB1InlzF4lZiVN3Gk%2Fimage.png?alt=media&amp;token=05e32dd8-061e-4368-8b5c-eade838711a6" alt="The My write access panel confirms that writes are not allowed yet. Check the environment badge, choose a duration, then click Allow writes."><figcaption><p>The My write access panel confirms that writes are not allowed yet. Check the environment badge, choose a duration, then click Allow writes.</p></figcaption></figure>

The same page shows the **Server URL** of the current environment, ready to copy into an MCP client. While writes are not allowed, the **My write access** panel reads "Writes are not allowed: your MCP clients can only read this tenant."

### Confirm and apply a write

Every write asks for confirmation before it acts. A client that supports it shows a yes or no form. Otherwise, the first call returns a preview with a summary, the changes, side effects, whether the change is reversible, and a confirmation token. Nothing is changed at that point. Repeating the same call with the token applies it. A token lasts 10 minutes and holds only for the same arguments, tool, tenant and user. Every preview and result names the environment.

Updates of themes, benefit templates and pass types replace the whole definition. The definition is read with the matching get tool, changed, and sent back whole; an omitted field is cleared. The last write wins, as in the console. An automation update changes only the fields sent.

Images are sent as an https URL on a public host or as base64 data. Only PNG and JPEG are accepted, up to 8 MB.

{% hint style="warning" %}
Some writes reach end-users at once. `twc_passes_update` pushes the pass to every device it is installed on, and its notification cannot be taken back. `twc_benefit_templates_update` with `refreshGrantedBenefits` pushes every pass carrying a benefit from that template. Deletes cannot be undone. Rehearse changes on QA first.
{% endhint %}

## Limits and connection behaviour

Opening a session requires a global administrator account or an account with a grant on at least one tenant. The endpoint contains no tenant path, so this connection gate is deliberately coarse. Each tool call decides real access.

Every tenant-scoped tool requires a specific Back-office scope. The platform enforces the same permission model as the REST API. Seeing a tenant in `twc_tenants_list` does not mean every tool succeeds against it. An authorization error means the scope is missing, not that the data is absent. `twc_security_permissions_list` explains a scope.

Calls are limited per tenant and per tool. The default is 60 calls per minute. A tenant can raise or lower this in `server/security.yml` under `mcpThrottling.defaultLimitPerMinute`, or set a per-tool limit under `mcpThrottling.limitsPerTool`.

Responses are capped at about 64,000 characters. Long lists are paged with a cursor, and a result that does not fit says so with a `truncated` flag or fails with a request to narrow it.

A tool call is capped at two minutes. Long calls, including `twc_insights_query`, stay alive through progress notifications. The server can only send these when the client supplies a progress token. A client that does not request progress may hit an upstream idle timeout without an error. Narrow time ranges in KQL queries avoid this.

The server uses Streamable HTTP in stateless mode. It has no standalone event stream. It sends no unsolicited notifications outside an in-flight call.

The server appends the environment to its name. For example, `The Wallet Crew MCP – Production`. Most clients display this name, which helps confirm the connected environment.

## Prompt patterns

Clear prompts produce focused investigations. Include the tenant context, timeframe, and expected outcome.

### Configuration health

> Run a full configuration validation for this tenant. Explain each error and recommend the next check.

### Recent regression

> Show configuration changes from the last 24 hours. Highlight the three highest-risk edits and explain why.

### Pass investigation

> Find pass `<PASS_ID>`. Summarize its current state and the latest significant lifecycle events, then show me what it looks like.

### Benefit investigation

> List benefit templates for this tenant. For template `<TEMPLATE_ID>`, show its full configuration and find all passes that currently hold an active benefit from it.

### Scheduled automation

> List automations for this tenant. For any that look wrong, show the configuration and the recent executions, and tell me whether it actually ran and succeeded.

### SFTP import triage

> Check whether SFTP is enabled for this tenant. List recent files, then for file `<FILE_NAME>` explain what happened during import, including which passes failed and why.

### Permission troubleshooting

> User `<EMAIL>` gets a 403 on `<OPERATION>`. Find their role, resolve its scopes, and tell me exactly which scope is missing or misspelled.

### Theme audit

> List pass themes and how many passes carry each. Flag themes with no passes and themes modified in the last 30 days.

### Access review

> Review Back-office users and API keys. Flag stale access and permissions that need review.

### Test change on QA

> On QA, issue a test pass of pass type `<PASS_TYPE>` with theme `<THEME_ID>`, then show me the preview and the install link.

## Safe operating practices

Use the documentation MCP for product knowledge before inspecting operational data. Start with the smallest scope that can answer the question.

Do not include customer data, tokens, API keys, or OAuth credentials in AI prompts. Review outputs before sharing them outside the authorized team.

Use QA for testing and rehearsals. Use production only when production evidence is required, and read every write preview before confirming it.

SFTP tools can return raw customer data. Use the narrowest window that answers the question.

## FAQ

<details>

<summary><strong>Does the documentation MCP require authentication?</strong></summary>

No. The documentation MCP is publicly accessible and returns documentation content only.

</details>

<details>

<summary><strong>Which credentials authenticate the QA and production MCP servers?</strong></summary>

Both servers use OAuth with the same credentials used for their respective Back-office environment. Existing Back-office permissions control available tenant access.

</details>

<details>

<summary><strong>Should QA and production use the same MCP connection?</strong></summary>

No. Each environment has a separate endpoint. Create clearly named connections to prevent an investigation from using the wrong environment.

</details>

<details>

<summary><strong>Can an AI assistant change data through the MCP server?</strong></summary>

Only through write tools, and only when the tenant allows MCP writes and the account has allowed writes on that tenant, for a limited time, from **Settings → Access control → MCP access** in the Back-office. Every write shows a preview or a confirmation form first, and nothing changes until it is confirmed.

</details>

<details>

<summary><strong>Can the MCP server return API-key secrets?</strong></summary>

No. API-key tools return permissions and status information. They do not return secrets.

</details>

<details>

<summary><strong>Why does a tool fail even though the tenant appears in <code>twc_tenants_list</code>?</strong></summary>

Connecting and calling are separate checks. `twc_tenants_list` returns tenants where the account has any grant. Each tool also requires its own permission scope on that tenant. Use `twc_security_roles_list` and `twc_security_permissions_list` to find the missing scope.

</details>

<details>

<summary><strong>Where did offers, privileges and pass templates go?</strong></summary>

They are now called benefit templates, benefits and pass types, matching the console. Use `twc_benefit_templates_list`, `twc_benefits_list` and `twc_pass_types_list`. Pass event history is read through `twc_insights_query`, and stamp card details are part of `twc_passes_get`.

</details>

<details>

<summary><strong>Are there rate limits?</strong></summary>

Yes. Calls are limited per tenant and per tool, with 60 calls per minute by default. A tenant can override the default or set a per-tool limit in its security configuration.

</details>


---

# 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://docs.thewalletcrew.io/connectors/model-context-protocol-mcp.md?ask=<question>&goal=<user_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.