What is UpVal?

UpVal is a values recognition platform for organisations. It gives staff a structured way to record when members demonstrate organisational values, and it builds a permanent, auditable history of each member’s character over time.

When a member accumulates enough recognition in a program, they can unlock an award: a pin, badge, certificate, or medal. UpVal tracks both the digital recognition event and whether the physical award has been handed over.

Three audiences, one platform. UpVal is used by coordinators (to give recognition), members (to track their own progress), and leaders (to see organisation-wide trends).

Key Concepts

Token: The fundamental unit of recognition. A token records that a specific member demonstrated a specific attribute at a specific moment. Tokens are immutable: once given, they cannot be edited or deleted. Each token belongs to one program and one attribute.

Attribute: A specific value or quality the organisation tracks (e.g. Integrity, Courage, Compassion). Attributes are organised into Attribute Groups (e.g. “Core Values”, “Houses”). When a token is given, the giver declares which attribute the member demonstrated. Attributes can also represent non-value categories like a house or class grouping.

Program: A named recognition initiative (e.g. “Values Program”, “House Points”, “Honour Roll”). Each program is linked to one attribute group, has its own token history, and defines its own award tiers. Every token belongs to exactly one program.

Award: A milestone a member earns when their token counts satisfy a program’s tier conditions. Awards have a physical counterpart (pin, certificate, badge, medal, or trophy). The system separately tracks whether the physical item has been issued to the member.

Award Tier: A defined threshold within a program (e.g. “Bronze: 10 Integrity tokens”). Tiers have conditions: each condition specifies an attribute and a minimum token count. A tier can require all conditions to be met or any one of them. Award eligibility is recalculated automatically whenever a member receives a new token.

Member: Any person with access to an organisation’s UpVal. Members have one of four roles: Owner, Admin, Coordinator, or Member (see Roles and Permissions).

Narrative: A written report summarising a member’s recognition history for a given date range. Narratives are initially AI-generated using a Narrative Type: a template with a name, AI instructions, and an optional program scope configured by the organisation. Once generated, the organisation can edit the report and publish it to the member.

Roles and Permissions

Owner — Full access. Can give recognition, view all profiles, manage members, and manage settings. One per organisation and cannot be removed.

Admin — Full access. Same permissions as Owner, except cannot remove the Owner.

Coordinator — Can give recognition and view all profiles, but cannot manage members or settings. Typical role for staff.

Member — Can view their own profile only. Cannot give recognition, manage members, or change settings. Typical role for participants.

Access is always scoped to the organisation. An AI agent connected via MCP inherits the permissions of the authenticated user and can only see and do what that user’s role allows.

Recognition

What it does: Records that a member demonstrated a specific attribute. Creates one token per recipient.

Required information:

• Program: which recognition initiative this belongs to
• Attribute: which value or quality the member demonstrated (must belong to the program’s attribute group)
• Recipients: one or more members to receive the token (each gets a separate token)
• Reason: a description of what the member specifically did (e.g. “Stayed calm and supported their team during a difficult project”)

What happens: Each recipient receives one token. The system immediately recalculates whether any of them have now met the conditions for an award in that program. If they have, the award is recorded automatically.

Who can give recognition: Owners, Admins, and Coordinators only. Members cannot give recognition; attempting to do so redirects to their own profile.

Member Profiles

A member’s profile contains:

• Token history: every token received, with the attribute, program, giver, date, and reason
• Program membership: which programs the member belongs to and their token counts per attribute
• Awards earned: which award tiers they have achieved and whether each has been issued
• Narratives: reports that have been generated and published for them

Access rules: Members can only access their own profile. Coordinators, Admins, and Owners can access any member’s profile.

Programs

A program is a named recognition initiative scoped to one attribute group. All tokens and awards within a program share the same set of attributes.

A program exposes aggregate token counts broken down by attribute and by a characteristic group (such as Cohort or Team). These counts can be scoped to a date range, defaulting to the current calendar year, which allows period-by-period comparisons.

Every token given in a program is recorded permanently. Each record includes the recipient, the attribute, the giver, the timestamp, and the reason. Token records are read-only.

Programs define award tiers that members can earn. Each tier has a name, a type (Certificate, Pin, Badge, Medal, or Trophy), and one or more conditions specifying a minimum token count for a given attribute. A tier can require all conditions to be met or any single condition. Once a member has earned a tier, that tier cannot be edited or deleted. New tiers can always be added.

When a member meets the conditions for a tier, an award is created for them. The physical item must still be handed to them separately. The program tracks this with an Issued status: marking an award as issued records that the physical item has been given to the member.

Narratives

Narratives turn token data into prose. A narrative is initially AI-generated for a specific member, using a specific narrative type, over a specific date range. Once generated, the organisation can edit the narrative and publish it to the member.

Narrative Types

A narrative type is a reusable template configured by an administrator. It defines:

• Name: how coordinators identify the type (e.g. “Term 1 Report”, “End-of-Year Summary”)
• AI instructions: the prompt that shapes the AI’s tone, format, and focus when writing
• Program scope (optional): if set, the narrative only draws on token data from those programs; if unset, it draws from all programs

Generating a Narrative

Required information:

• Narrative type: the template to use
• Date range: start and end date for the period to summarise
• Members: one or more members to generate reports for

Narratives process asynchronously. Status progresses through: Pending → Generating → Complete (or Error). Once complete, the report is available for editing.

Re-generating for the same member + type + date range replaces the previous result.

Who can generate: Coordinators, Admins, Owners.

Editing and Publishing

Once generated, a narrative can be edited before being published. Publishing makes the narrative visible to the member. An unpublished narrative is only visible to Coordinators, Admins, and Owners.

Who can edit and publish: Coordinators, Admins, Owners.
Who can read published narratives: Members can view narratives published for them.

Administration

Managing Members

To add a member, provide their email address and assign a role. If they have no existing account, one is created automatically on first sign-in.

Members can be removed unless they have token history attached.

Setting Up Attributes

Attributes must be configured before programs, because programs are linked to an attribute group.

Setup order:

1. Create one or more Attribute Groups (e.g. “Core Values”)
2. Add Attributes to each group (e.g. Integrity, Courage, Compassion)

Each attribute can have an associated colour used in dashboards and labels.

Setting Up Programs

Programs are linked to one attribute group at creation time; this cannot be changed later.

Setup order:

1. Create the program with a name, description, and attribute group
2. Add award tiers to the program, each with conditions

Setting Up Narrative Types

Create narrative types before coordinators can generate narratives. Each type needs a name and AI instructions. Program scope is optional.

AI Assistant Access

UpVal exposes most of its data and operations through MCP (Model Context Protocol). An AI assistant with MCP access can perform the same tasks as the authenticated user in the web app without touching the UI.

The MCP endpoint for your organisation is: https://mcp.upval.app/{your-org-slug}

Your org slug is visible in organisation settings. The AI assistant authenticates as you and operates within your role’s permissions.

Adding to Claude: Go to Settings → Connectors → Customize → Add custom connector, provide a name paste the MCP URL, and follow the sign-in prompt.

Adding to ChatGPT: Open a project, go to Connectors → Add connector → MCP, paste the MCP URL, and authorise.

MCP access is per-account. The assistant sees exactly what you can see.