Configuring MCP (Model Context Protocol)

Optionally connect an MCP endpoint so AI Companion can fetch extra context (e.g. user data, account info) when generating reply suggestions. You provide a URL, a secret for authentication, and a JSON schema that describes the body your endpoint expects.

What is MCP?

MCP (Model Context Protocol) lets you expose an HTTPS endpoint that returns data for the AI. When a customer message is being processed, SupportRetriever can call your endpoint with a JSON body (shaped by your schema) and use the response to enrich suggestions. Typical uses:

Look up customer or account data by email or ID
Fetch subscription or usage info
Pull in data from your own backend or CRM

Your secret key is stored encrypted and never returned. Only the URL, schema (body), and field mappings are stored in plain form.

When to Use MCP

Use MCP when:

You want the AI to have access to data that isn’t in your knowledge base (e.g. per-user or per-account data).
That data lives behind an API you control and can expose over HTTPS with a shared secret.

You can use both a knowledge base URL and MCP together: the knowledge base provides general docs, and MCP provides request-specific context.

Setting Up MCP

Go to AI Companion settings and expand the MCP section (click Edit next to MCP if it’s collapsed).
Enter your URL (must be HTTPS), e.g. https://api.example.com/mcp.
Enter your Secret key (used to authenticate requests to your endpoint). It is encrypted before storage. Leave the field blank when editing if you don’t want to change the existing secret.
Enter the Body as a JSON schema that describes the payload your endpoint expects (e.g. JSON Schema with a top-level properties object).
If the schema has properties, a Field mapping table appears. For each property, choose where the value comes from:
- Customer name – from the submission’s name field
- Customer email – from the submission’s email field
- Metadata key – from form submission metadata (e.g. URL params like ?userId=123); enter the metadata key name (e.g. userId).
Click Save to store the configuration, or Remove MCP to clear it.

URL and Secret

URL: Must be a valid HTTPS URL. SupportRetriever will send a request to this URL when context is needed (implementation of the actual call is handled by the product; this article describes configuration only).
Secret key: Stored encrypted. Use it on your server to verify that requests are from SupportRetriever (e.g. via header or signature). Never share it; rotate it if compromised.

Body (JSON Schema)

The Body should be a JSON schema that defines the structure of the request body sent to your endpoint. For example:

{
  "type": "object",
  "properties": {
    "uid": { "type": "string", "description": "Firebase UID" },
    "emails": {
      "type": "array",
      "items": { "type": "string", "format": "email" },
      "maxItems": 10,
      "description": "Look up by email(s)"
    }
  }
}

Once you paste a valid schema with a top-level properties object, the UI shows a Field mapping table so you can map each property to a data source (customer name, customer email, or a metadata key).

Field Mapping

Mapping connects each schema property to where the value comes from at request time:

Customer name – value from the form submission’s name field.
Customer email – value from the form submission’s email field.
Metadata key – value from submission metadata (e.g. from URL parameters when the form was opened). Enter the exact key name (e.g. userId, campaign).

For array or object properties, the mapped value is still a single source (e.g. one metadata key or email); how you build the final body is determined by the product when it calls your endpoint.

Removing MCP

In the MCP section, click Remove MCP. This clears the URL, secret, body, and mappings. Your AI Companion and knowledge base settings are unchanged.