> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sprig.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsert Users with MCP

The Sprig MCP server can create and update users and their attributes in your workspace. This is useful when you want to keep your user records in sync with an external system, or seed your workspace with users before importing their responses.

> [!NOTE]
>
> This feature requires the `users:write` OAuth scope, which is available to users with the admin, developer, editor, or editor-lite role. The `viewer` and `super_admin` roles cannot grant this scope.

## Tool: `upsert_user_attributes`

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `environment_id` | string | Yes | The ID of the environment to upsert the user in |
| `user_id` | string | Yes | A unique identifier for the user within your system |
| `attributes` | object | Yes | Key-value pairs where keys are strings and values are boolean, number, or string (up to 255 characters) |
| `email_address` | string | No | The user's email address |

## Example Prompts

1. **Upsert a single user** *Upsert a user with ID `user-123` and attributes `plan: pro`, `seats: 10`.*
2. **Create a user with email** *Create a user with email `jane@example.com` and attributes `company: Acme`, `industry: software`.*
3. **Update a user's attributes** *Update the attributes for user `user-123` to set `last_seen: 2026-10-23`.*

## How It Works

1. Your AI client sends an `upsert_user_attributes` tool call with the user's ID, attributes, and optional email address.
2. The Sprig MCP server sends a `POST /v2/users` request to the Sprig public API.
3. The API creates the user if they don't exist, or updates their attributes and email if they do.
4. The MCP server returns `{ "accepted": true }` when the request is queued for processing.

> [!NOTE]
>
> The upsert is asynchronous — a `202 Accepted` response confirms the request was queued, not that the attributes are immediately readable. Attribute changes are applied shortly after the request is accepted.

## Permissions

The `users:write` scope is only offered to users with roles that can upload a visitor CSV in Sprig: **admin**, **developer**, **editor**, and **editor-lite**. Users with the `viewer` role, or Sprig super admins, will not be prompted for this scope during OAuth authorization.

All MCP activity is subject to the same data protections described in [MCP Security](https://docs.sprig.com/docs/native-ai/mcp-security.md).

> [!NOTE]
>
> **Need help?** Contact [support@sprig.com](mailto:support@sprig.com) or reach out to your dedicated customer success representatives.