Backstop MCP - Configuration

Overview

All configuration is through environment variables. Every variable this service defines is listed on this page, grouped the way config.py groups them. The FASTMCP_* and OTEL_* variables read by the FastMCP and OpenTelemetry libraries are not covered and not supported.

• App default is what the server uses when the variable is unset.

• Chart default is what the Helm chart's values.yaml sets under env. A blank cell means the chart leaves it to the app.

• Most values are validated at startup, and a value outside its allowed range stops the server. The error names the settings class and field, for example BackstopConfig / max_retry_attempts for BACKSTOP_MAX_RETRY_ATTEMPTS. BACKSTOP_CUSTOM_FIELD_SCHEMA_TTL_MINUTES is clamped instead.

• SEARCH_*, RESOLUTION_*, PRODUCT_INVESTORS_*, and ACTIVITY_HISTORY_* are read on the first tool call that uses them. A bad value there does not stop startup; it fails those tool calls.

• Variable names are case-insensitive, except DATABASE_URL and LOGS_DIAGNOSTICS_DATA_POLICY, which must be upper case. Booleans accept true / false.

Only two variables have no usable default in production: PUBLIC_BASE_URL and BACKSTOP_MCP_ENCRYPTION_KEY. A database connection is also required.

Setting values with Helm

Chart values

The settings that differ per firm have typed values under mcpConfig:

mcpConfig:
  app:
    publicBaseUrl: https://backstop-mcp.example.com
  backstop:
    baseUrl: https://<firm>.backstopsolutions.com
    uiBaseUrl: https://<firm>.backstopsolutions.com
  employment:
    formerRelationshipTypeIds: ["1042", "1043"]

• A misspelt key fails helm install against the chart schema. A URL must start with http:// or https://, and a list item cannot contain a comma. Ids are strings: quote them (["1042"]), or the schema rejects them.

• A URL is rendered only when it is not empty, so an empty value keeps the app default. URLs pass through tpl, so an overlay can build them from other values. The schema checks the raw value before tpl runs, so the scheme must be literal: https://{{ .Values.routes.hostname }} passes, while {{ printf "https://%s" .Values.routes.hostname }} is rejected.

• A list is rendered comma-separated whenever it is set, including [], which reaches the app as an empty value. The chart default null leaves the variable unset. This matters for the markers lists: [] replaces their defaults, null keeps them. See Departed-contact detection.

• mcpConfig.tenantGuidance is rendered only when it is not empty.

• mcpConfig.enabled: false renders none of these variables, tenant guidance included.

• A variable set both under mcpConfig and under env takes the mcpConfig value. env reaches the container through a ConfigMap (envFrom), and Kubernetes gives a container's own env entries precedence over it. A deployment that still sets these variables under env keeps working, and can move them to mcpConfig at any time.

Required

Application

Backstop API

Where to reach Backstop and how the shared HTTP client behaves. Prefix BACKSTOP_.

CRM links

Tools that return a record also return its Backstop UI url, and build_backstop_links builds tab and layout links. The origin is chosen like this:

1. BACKSTOP_UI_BASE_URL when set.

2. Otherwise BACKSTOP_BASE_URL, but only when its host is not api.backstopsolutions.com. A tenant host is assumed to also serve the UI.

3. Otherwise no links: record url fields are empty and build_backstop_links answers not_configured.

Set BACKSTOP_UI_BASE_URL explicitly whenever BACKSTOP_BASE_URL is not the tenant's own host. A regional or staging API host would otherwise be used as a UI origin and produce links that do not load.

Catalog Caches

Several tools read small instance-wide catalogs (custom-field definitions, activity tags, system users, and so on). Each catalog has an on/off flag and a TTL. With the flag off, every read fetches the catalog from Backstop again. Concurrent requests for the same catalog share one fetch either way.

• Every TTL is in minutes, between 1 and 1440 (24 hours). A custom-field TTL above 1440 is lowered to 1440 instead of failing startup.

• A TTL is ignored while its flag is off.

• The custom-field cache is on because large tenants have thousands of definitions and one walk takes several seconds; every party and product read joins against it.

• list_custom_fields, list_custom_field_groups, list_activity_tags, list_contact_sources, list_contact_categories, and list_system_users accept refresh=true to fetch again regardless of the TTL.

• When a cached catalog's refresh fails, the previous copy keeps being served and the TTL restarts. Opportunity stages and relationship types are the exception: a failed refresh fails the call.

• To decide whether to turn a cache on, compare catalog_get_duration_seconds_count (demand) with catalog_fetch_duration_seconds_count (actual walks). See Architecture: Observability.

Departed-Contact Detection

get_person, get_people_for_party, and search_people report whether a person's link to an organization is current or former. A firm may record a departure as a separate relationship type ("is a former employee of") rather than an end date, so the server needs to know which relationship types mean employment and which mean it has ended.

• All four are comma-separated; in Helm they are lists. Setting a markers variable replaces its defaults; setting it empty ([] in Helm) leaves only the ids for that bucket. Leave the chart value null to keep the defaults.

• The two marker lists must not overlap. A shared substring such as employee cannot tell a current type from a former one, which is why the departure word is the marker. This is not checked at startup: an overlap silently misclassifies links.

• Ids differ per Backstop instance and have no default. GET /entity-relationship-types lists them.

• An organization's own record returns the mirror type ("… (mirror)") with a different id. Markers match both directions; if you configure former ids, include the mirror type's id too.

Tool Behaviour

Tenant Guidance

BACKSTOP_MCP_TENANT_GUIDANCE adds firm-specific text to what the AI reads, without changing the shipped tool descriptions. In Helm, set the mcpConfig.tenantGuidance object; the chart renders it as JSON into the variable, and omits the variable when the object is empty.

mcpConfig:
  tenantGuidance:
    server_instructions: >-
      "Strategy" on a product is the custom field named Investment Strategy.
    tools:
      search_products:
        description: Fund short names start with NW, for example NWGM.
        parameters:
          name: Short names are upper case.

• An unknown tool or parameter name stops startup, and the error lists the valid names.

• Unknown keys are rejected.

• Empty or unset means the shipped descriptions only.

Database

Without a URL, DB_HOST, DB_NAME, DB_USER, and DB_PASSWORD are all required and startup names the missing ones.

TLS is read from the URL's sslmode parameter:

• verify-ca and verify-full check the certificate against the container's system CA bundle. sslrootcert and the other libpq certificate parameters are not supported (the driver rejects them), so a database with a privately signed certificate can only use require.

• With postgresql.connection.url, put sslmode in the URL. The chart's postgresql.connection.sslMode and the PG_DATABASE_SSL_MODE variable it sets are not read by this server.

• With postgresql.connection.host, database, username, and password, the chart builds DATABASE_URL itself with sslmode=<postgresql.connection.sslMode>, default verify.

Migrations (alembic upgrade head) read the same variables as the server.

Authentication and Encryption

Token lifetimes (15-minute access, 30-day refresh) are fixed in code. See Authentication: Token lifetimes.

Related

• Operator Guide

• Overview

• Authentication

• Local Development: the minimum .env for a local run, based on the commented .env.example

• Architecture: Observability