# RevCent MCP Operation: `EditKeyValue`

This document explains how MCP/AI clients should use the `EditKeyValue` operation in RevCent.

A Key Value is an account-wide value accessible by a unique key. Key Values are useful for shared configuration, reusable shortcodes, API-call pointers, and Function state/configuration.

Sources:
- RevCent operation schema for `EditKeyValue`
- RevCent operation schema for `CreateKeyValue`
- RevCent operation schema for `GetKeyValue`
- RevCent operation schema for `GetKeyValues`
- RevCent Knowledge Base: https://kb.revcent.com/en/tools/key-value

---

## Operation Summary

`EditKeyValue` edits a specific system-wide Key Value using its key.

The schema states:

```text
Only use this operation if explicitly told to edit a Key Value.
Key Values are not related to metadata.
```

Required:

```text
key
```

Editable:

```text
description
value
key_type
pointer_type
```

Important:

```text
The key itself cannot be modified once created.
```

If the user wants a different key name, create a new Key Value with the new key and, if appropriate, update references that use the old key.

---

# Critical Rule: Only Edit When Explicitly Asked

MCP/AI should only call `EditKeyValue` when the user or client explicitly asks to edit/update/change a Key Value.

Correct user intent:

```text
Edit the Key Value support_email.
Update the active_payment_profile Key Value.
Change the value of daily_report_cursor.
Set fraud_alerts_enabled to false.
```

Incorrect MCP behavior:

```text
The user mentioned a value, so I will update the Key Value.
The value seems stale, so I will change it.
The user asked to change metadata, so I will edit a Key Value.
```

Rule:

```text
No explicit Key Value edit request = no EditKeyValue call.
```

---

# Key Values Are Not Metadata

Do not use `EditKeyValue` for metadata updates.

| Concept | Purpose |
|---|---|
| Key Value | Account-wide value accessed by key across supported RevCent tools/features. |
| Metadata | Data attached to a specific item, such as a customer, sale, transaction, or other record. |

If the user asks to edit metadata, use metadata operations instead.

---

# Required Field

| Field | Type | Required | Description |
|---|---:|---:|---|
| `key` | string | Yes | The existing Key Value key. The key cannot be modified. |

---

# Editable Fields

| Field | Type | Description |
|---|---:|---|
| `description` | string | Key description. Maximum 255 characters. |
| `value` | string | Key value. Cannot exceed 5 MB. |
| `key_type` | enum | Either `string` or `pointer`. |
| `pointer_type` | enum | Required if `key_type = pointer`. Currently supports `payment_profile`. |

The schema has:

```json
"additionalProperties": false
```

Do not send unknown fields.

---

# Partial Edit Behavior

`EditKeyValue` is a partial edit operation.

Only include fields the user wants to change.

Correct value-only edit:

```json
{
  "key": "support_email",
  "value": "help@example.com"
}
```

Correct description-only edit:

```json
{
  "key": "support_email",
  "description": "Primary support email used in Email Templates and AI Assistant messages."
}
```

Correct conversion to pointer:

```json
{
  "key": "active_payment_profile",
  "key_type": "pointer",
  "pointer_type": "payment_profile",
  "value": "Primary Credit Card Profile"
}
```

---

# Retrieve Before Editing

Before meaningful edits, MCP/AI should retrieve the existing Key Value using:

```text
GetKeyValue
```

Review:

```text
key
description
value
key_type
pointer_type
created_date_unix
updated_date_unix
```

This is especially important when:

- Changing `key_type`
- Changing a pointer target
- Updating Function state
- Changing a value used by Email Templates
- Changing a value used by AI Assistants
- Changing a value used by API-call pointers
- Changing a value used by Functions

---

# `key`

The `key` identifies the existing Key Value.

The key cannot be modified.

Rules:

```text
Minimum length: 2
Maximum length: 100
Alphabetical characters and underscores only
Cannot start with underscore
Cannot end with underscore
Cannot contain spaces
Cannot contain numbers
Cannot contain hyphens
Cannot contain periods
```

If the user wants to rename a key:

```text
1. Create a new Key Value with the desired key.
2. Copy or set the desired value.
3. Update all references to use the new key.
4. Optionally stop using the old key.
```

Do not attempt to edit the key name.

---

# `description`

Use description to document what the Key Value is for.

Examples:

```text
Support email used in Email Templates and AI Assistant messages.
```

```text
Pointer to the active payment profile used by API-call pointer shortcuts.
```

```text
Function-managed cursor storing the last processed sale ID for nightly reporting.
```

Description maximum:

```text
255 characters
```

---

# `value`

The `value` field replaces or updates the stored value.

Maximum size:

```text
5 MB
```

For `key_type = string`, value is a raw string.

For `key_type = pointer`, value must match an existing item corresponding to `pointer_type`.

If `pointer_type = payment_profile`, then `value` must match an existing payment profile ID or name.

MCP/AI should verify pointer targets before editing.

---

# `key_type`

Allowed values:

```text
string
pointer
```

## Editing to `string`

Use `string` for:

- Raw text
- Shared shortcodes
- Function state
- JSON state
- Feature flags
- Dynamic config

Example:

```json
{
  "key": "fraud_alerts_enabled",
  "key_type": "string",
  "value": "false"
}
```

## Editing to `pointer`

Use `pointer` when the Key Value should point to a supported RevCent entity.

Currently supported pointer type:

```text
payment_profile
```

Example:

```json
{
  "key": "active_payment_profile",
  "key_type": "pointer",
  "pointer_type": "payment_profile",
  "value": "XXXXXXXXXXXXXXXXXXXX"
}
```

---

# `pointer_type`

Required when:

```text
key_type = pointer
```

Currently supported:

```text
payment_profile
```

When changing or setting a payment profile pointer:

1. Verify the payment profile exists.
2. Use the payment profile ID or exact name.
3. Ensure API calls using the pointer expect a payment profile pointer.
4. Confirm the change will not break live API-call workflows.

---

# Key Value Availability Across RevCent

The Key Value KB describes where Key Values can be used.

## Email Templates

Email Templates use double-curly shortcode syntax:

```handlebars
{{key_values.my_key}}
```

Example:

```handlebars
Need help? Email {{key_values.support_email}}.
```

Changing a Key Value used in Email Templates can change future compiled email content.

---

## AI Assistant Messages

AI Assistant messages use bracket shortcode syntax:

```text
[key_values.my_key]
```

Example:

```text
You can contact us at [key_values.support_email].
```

Changing a Key Value used by AI Assistants can change future assistant messages.

---

## API Call Pointers

API calls can use pointer Key Values with bracket shortcode syntax:

```text
[key_values.my_key]
```

Important:

```text
Only pointer key types are supported in API calls at this time.
String key types are not supported in API calls to avoid misconfiguration and payment errors.
```

Example:

```json
{
  "payment_profile": "[key_values.active_payment_profile]"
}
```

If the pointer target changes, future API calls using the shortcode may use a different payment profile.

This can be high-impact.

---

## Functions

Functions can read Key Values using:

```javascript
global["revcent"].GetKeyValue(my_key, callback)
```

Functions can update string Key Values using:

```javascript
global["revcent"].UpdateKeyValue(my_key, value, callback)
```

Important:

```text
Only string Key Values can be updated within a Function.
Pointer Key Values cannot be updated within a Function.
```

---

# Editing Key Values Used for Function State Management

Key Values are useful for Function state management because Functions can read and update string Key Values.

Common Function state keys:

```text
last_processed_sale
daily_report_cursor
shippo_sync_cursor
fraud_alerts_enabled
vip_ltv_threshold
last_support_outreach_unix
```

State values are often JSON strings.

Example:

```json
{
  "last_processed_sale_id": "XXXXXXXXXXXXXXXXXXXX",
  "last_run_unix": 1770000000,
  "version": 1
}
```

When editing state manually, MCP/AI should be careful.

Manual edits can affect future Function behavior.

For example:

```text
Changing last_processed_sale may cause a Function to skip records or reprocess records.
Changing daily_report_cursor may duplicate or suppress reports.
Changing fraud_alerts_enabled may stop or resume external alerts.
Changing vip_ltv_threshold may change which customers are flagged as VIP.
```

---

# Function State Edit Best Practices

Before editing a Function-managed Key Value:

1. Retrieve the current value.
2. Identify which Function reads or updates the key.
3. Understand how the Function uses the value.
4. Preserve JSON structure if the value is JSON.
5. Do not corrupt state by replacing JSON with invalid text.
6. Do not convert Function state keys to pointer type.
7. Confirm whether the Function can safely continue after the edit.
8. Avoid editing high-frequency state while the Function may be actively running.
9. Do not assume updates are atomic unless RevCent documents atomic behavior.
10. Keep the value under 5 MB.

---

# Function Code Example: Read and Update State

```javascript
global["revcent"].GetKeyValue("daily_report_cursor", function(error, value) {
  if (error) {
    callback(error);
    return;
  }

  let state = {};
  try {
    state = JSON.parse(value || "{}");
  } catch (parseError) {
    callback(parseError);
    return;
  }

  // Use state.last_run_unix or state.last_processed_sale_id here.

  const nextState = JSON.stringify({
    last_run_unix: Math.floor(Date.now() / 1000),
    last_processed_sale_id: "XXXXXXXXXXXXXXXXXXXX"
  });

  global["revcent"].UpdateKeyValue("daily_report_cursor", nextState, callback);
});
```

Key points:

```text
Get current state first.
Parse carefully.
Update only string Key Values.
Call callback to end Function execution.
```

---

# High-Impact Edits

Some Key Value edits are high-impact.

## Payment Profile Pointer Changes

If a pointer Key Value is used in API calls:

```json
{
  "payment_profile": "[key_values.active_payment_profile]"
}
```

changing the pointer target can change which payment profile future API calls use.

This can affect live payment processing.

Before changing a payment profile pointer, MCP/AI should confirm:

1. Which payment profile it points to now.
2. Which payment profile it will point to after edit.
3. Which workflows or API calls use the key.
4. Whether the target payment profile is enabled and correct.
5. Whether the user understands the routing impact.

## Email Template Shortcode Changes

Changing a value used in Email Templates changes future rendered email content.

## AI Assistant Message Changes

Changing a value used in AI Assistant messages changes future AI Assistant messages or branch messages.

## Function State Changes

Changing Function state can change future automation behavior.

---

# Edit Examples

## Example 1: Update Support Email

```json
{
  "key": "support_email",
  "value": "help@example.com"
}
```

---

## Example 2: Update Description

```json
{
  "key": "support_email",
  "description": "Primary support email used by templates and AI Assistant messages."
}
```

---

## Example 3: Change Active Payment Profile Pointer

```json
{
  "key": "active_payment_profile",
  "key_type": "pointer",
  "pointer_type": "payment_profile",
  "value": "New Primary Credit Card Profile"
}
```

Before this edit, verify the payment profile exists and confirm impact.

---

## Example 4: Manually Reset Function Cursor

```json
{
  "key": "daily_report_cursor",
  "key_type": "string",
  "value": "{\"last_run_unix\":0,\"last_processed_sale_id\":null}"
}
```

Use only if the user understands this may cause the related Function to reprocess or restart its state.

---

# MCP Edit Workflow

Before calling `EditKeyValue`, MCP/AI should:

1. Confirm the user explicitly asked to edit a Key Value.
2. Confirm the user is not asking to edit metadata.
3. Retrieve the existing Key Value using `GetKeyValue`.
4. Determine what fields should change.
5. Confirm the key is correct.
6. If changing value, validate the new value.
7. If value is JSON, validate JSON syntax.
8. If changing to pointer, verify pointer target exists.
9. If changing a payment profile pointer, confirm payment routing impact.
10. If changing Function state, confirm Function behavior impact.
11. Submit only intended fields.
12. Verify the resulting Key Value after edit if necessary.

---

# Validation Checklist

Before submitting `EditKeyValue`:

1. `key` is present.
2. `key` is the existing key and not a new desired name.
3. User explicitly requested Key Value edit.
4. User is not asking for metadata.
5. Existing Key Value was retrieved when impact matters.
6. Only intended fields are included.
7. No unknown fields are included.
8. If `description` is included, it is under 255 characters.
9. If `value` is included, it is under 5 MB.
10. If `value` is JSON, it is valid JSON.
11. If `key_type` is included, it is `string` or `pointer`.
12. If `key_type = pointer`, `pointer_type` is present.
13. If `pointer_type = payment_profile`, target payment profile exists.
14. If editing a Function-managed key, Function state impact is understood.
15. If editing an API-call pointer, payment/API workflow impact is understood.

---

# Output Schema

Successful response:

```json
{
  "api_call_id": "XXXXXXXXXXXXXXXXXXXX",
  "api_call_unix": 1740000000,
  "code": 1,
  "key": "support_email",
  "description": "Primary support email used by templates.",
  "value": "help@example.com",
  "key_type": "string",
  "pointer_type": null,
  "result": "..."
}
```

---

# Common Mistakes

## Mistake: Trying to Rename the Key

The key cannot be modified once created.

Create a new Key Value instead.

## Mistake: Editing Metadata With EditKeyValue

Key Values are not metadata.

Use metadata operations for metadata.

## Mistake: Changing a Payment Profile Pointer Without Impact Review

A payment profile pointer may affect future API calls and payment routing.

## Mistake: Updating Pointer Key Values From Functions

Functions can only update string Key Values.

Pointer Key Values cannot be updated within a Function.

## Mistake: Corrupting JSON State

If a Function expects JSON state, do not replace the value with invalid JSON.

---

# Key Takeaways

```text
EditKeyValue edits the value, description, key type, or pointer target for an existing key.
```

```text
The key itself cannot be modified.
```

```text
Key Values are not metadata.
```

```text
Pointer Key Values can affect API-call routing, especially payment profile pointers.
```

```text
String Key Values are useful for Function state management.
```

```text
Functions can read Key Values and update only string Key Values through the global revcent object.
```


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.