> 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.
Real-world examples
* 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 task.
## 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:**
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:**
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:**
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 | |
| QA — test data | |
Nothing needs installing or downloading. No key, password, or code is needed.
{% hint style="success" %}
The connection is read-only. An AI assistant can look things up. It cannot change, delete, or send anything. It only sees data already available through the Back-office account.
{% 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 offers are running right now, and how many customers hold each one?”
* “Show me the pass with serial number `` 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. |
| 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 control plane. It exposes 37 tools for tenant-scoped configuration, telemetry, pass operations, scheduling, redirects, and access posture.
### Discover tenants and configuration
Start every operational session by resolving the tenant from the available tenant list. Never infer or guess a tenant identifier.
| Capability | Available tools | Typical outcome |
| --------------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
| List accessible tenants | `tenants_list` | Resolve the correct tenant before investigation |
| Review tenant baseline | `config_get` | Inspect identity, lifecycle, localization, and integrations |
| Inspect configuration files | `config_files_list`, `config_files_get` | Find current or historical configuration values |
| Audit configuration changes | `config_history_list`, `config_files_diff` | Identify when and how a configuration changed |
| Validate configuration | `config_schema_list`, `config_schema_get`, `config_test` | Check schema requirements and surface validation errors |
### Investigate integrations and telemetry
Use integration and telemetry tools to validate runtime behavior and identify anomalies.
| Capability | Available tools | Typical outcome |
| --------------------------- | -------------------------------------------- | --------------------------------------------------------- |
| Review enabled extensions | `extensions_list` | Identify enabled integrations and their permission scopes |
| Explore telemetry structure | `insights_schema`, `insights_query_examples` | Build valid KQL queries |
| Query tenant telemetry | `insights_query` | Investigate errors, trends, and unexpected behavior |
### Review passes and offers
Use pass and offer tools to investigate customer-impacting workflows.
| Capability | Available tools | Typical outcome |
| ------------------------ | ---------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Discover pass templates | `passes_templates_list` | Find template names, metadata fields, and scannable data |
| Find and inspect passes | `passes_list`, `passes_get` | Review a pass and its current state |
| Reconstruct pass history | `passes_events_list`, `passes_privileges_list` | Review lifecycle events, balances, and redemptions |
| Inspect a stamp card | `passes_stamps_get` | Read the current count, target, goal behaviour and full movement history |
| Review offer definitions | `offers_list`, `offers_get` | Browse available offers and inspect type, category, validity, and linked pass template |
| Trace issued privileges | `offers_privileges_list` | Find all passes that received a specific offer, or match any external process identifier |
| Audit short URLs | `redirects_list` | Find redirects and review expiration details |
`passes_stamps_get` fails when the pass is not a stamp card. A card never stamped returns a count of `0` against its configured target.
### Review automations
Automations describe intent. Executions describe outcome. Use both when diagnosing “the automation did not run”.
| Capability | Available tools | Typical outcome |
| ------------------------------------- | ----------------------------- | ------------------------------------------------------------------------- |
| List automations | `automations_list` | See every automation, enabled first, with a plain-English trigger summary |
| Inspect one automation | `automations_get` | Read the full settings, trigger fields and enabled state |
| Check whether it actually ran | `automations_executions_list` | Confirm success, failure or postponement from telemetry |
| Review the underlying scheduled tasks | `scheduler_tasks_list` | Read `server/scheduler.yml` tasks and their trigger types |
> `scheduler_tasks_list` and `automations_list` both describe configuration, not outcome. Only `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, `false` means it ran and threw, and `true` means it completed.
* `recurrence` — a cron expression including seconds, evaluated in **UTC**, not tenant local time.
* `fixedDate` — fires once at a given instant. A fixed date in the past never fires.
* `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 when an event occurs, such as installation. `firstInstallationOnly` means re-installation does not fire it again.
### 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 whether SFTP is in use | `sftp_status_get` | Confirm the feature is enabled and read a quick activity summary |
| List dropped files | `sftp_files_list` | See each file tagged `pending`, `processed` or `error` |
| Explain one import | `sftp_import_log_get` | Read row counts and per-pass outcomes, with the failure reason |
| Inspect raw file content | `sftp_file_read` | Page through raw lines to spot delimiter, column or identifier problems |
* File statuses: `pending` means dropped, not yet picked up, and still in flight. `processed` means imported and terminal. `error` means processing failed and is terminal. Use `sftp_import_log_get` to find out why.
* `sftp_import_log_get` distinguishes `noMatchCount` from `errorCount`. The first counts rows whose identifiers matched no pass. It signals data quality, not a pipeline bug. The second counts rows that threw during processing.
* The import story is reconstructed from Application Insights by file name, not an exact correlation ID. A file re-uploaded with the same name several times quickly may mix runs. `passId` may be unavailable after the 90-day log retention window.
* `sftp_file_read` returns a capped window of lines. Pass the previous result’s `nextStartLine` as `startLine` to continue. `truncated` set to `false` and `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. `sftp_file_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 %}
### Review pass themes
Themes make pass visuals consistent across a tenant.
| Capability | Available tools | Typical outcome |
| ----------------- | --------------- | ------------------------------------------------------------------------------- |
| List themes | `themes_list` | See each theme with how many passes currently carry it |
| Inspect one theme | `themes_get` | Read colors, localized title and description, and every per-slot image override |
* A theme is a reusable visual skin with colors 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 the next render. Read `lastModificationDate` and `passCount` together.
* A theme has no behaviour, validity window, or code. For anything customers can redeem, review offers and privileges.
* `themes_list` provides the theme ID used by the `themeId` filter of `passes_list`.
* In `themes_get`, `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, icon, and venue map are set only through `images`. Per-language images apply only to Apple Wallet. Google Wallet always serves the default.
### Review access posture
Security tools return access metadata, not API-key secrets.
| Capability | Available tools | Typical outcome |
| -------------------------------- | --------------------------- | --------------------------------------------------------------------------------- |
| Review Back-office users | `security_users_list` | Check roles and recent sign-in metadata |
| Review API keys | `security_apikeys_list` | Check permissions and enabled status without exposing secrets |
| Review roles and what they grant | `security_roles_list` | See each role as stored, fully resolved, and the entries that resolve to nothing |
| Understand a permission scope | `security_permissions_list` | Turn a scope code into a plain-language meaning, or find the right scope to grant |
To explain a 403, find the person’s role with `security_users_list`. Then check whether the required scope appears in 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. Confirm extensions with `extensions_list`. 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.
## 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 `tenants_list` does not mean every tool succeeds against it. An authorization error means the scope is missing, not that the data is absent. Use `security_permissions_list` to look up 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`.
A tool call is capped at two minutes. Long calls, including `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. Prefer narrow time ranges in KQL queries.
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 ``. Summarize its current state and the latest significant lifecycle events.
#### Offer investigation
> List offers for this tenant. For offer ``, show full configuration and find all passes that currently hold an active privilege 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 `` explain what happened during import, including which passes failed and why.
### Permission troubleshooting
> User `` gets a 403 on ``. 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.
## 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.
SFTP tools can return raw customer data. Use the narrowest window that answers the question.
## FAQ
Does the documentation MCP require authentication?
No. The documentation MCP is publicly accessible and returns documentation content only.
Which credentials authenticate the QA and production MCP servers?
Both servers use OAuth with the same credentials used for their respective Back-office environment. Existing Back-office permissions control available tenant access.
Should QA and production use the same MCP connection?
No. Each environment has a separate endpoint. Create clearly named connections to prevent an investigation from using the wrong environment.
Can the MCP server return API-key secrets?
No. API-key tools return permissions and status information. They do not return secrets.
Why does a tool fail even though the tenant appears in tenants_list?
Connecting and calling are separate checks. `tenants_list` returns tenants where the account has any grant. Each tool also requires its own permission scope on that tenant. Use `security_roles_list` and `security_permissions_list` to find the missing scope.
Are there rate limits?
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.
---
# 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=&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.