---
title: "context"
description: "Account-specific reference data — statuses, pipelines, users, tags, custom fields, and the values an agent needs to make valid writes."
canonical_url: https://developer.onepagecrm.com/mcp/tools/context/
source: Markdown mirror of https://developer.onepagecrm.com/mcp/tools/context/
---

`context` returns the account-specific reference data an agent needs
before it can build a valid `create` or `update` payload. `describe`
tells the agent *which fields exist*; `context` tells it *which values
are valid for this account right now* — the user list, the pipeline
stages, the contact statuses, the custom fields defined on this CRM.

## Signature

```json
{
  "type": "object",
  "properties": {}
}
```

`context` takes no arguments.

## What it returns

| Key             | Contents                                                              |
| --------------- | --------------------------------------------------------------------- |
| `statuses`      | Contact statuses configured for this account.                         |
| `lead_sources`  | Lead sources available when creating or updating a contact.           |
| `call_results`  | Outcomes that can be set on a `call` (e.g. "Reached", "Left voicemail"). |
| `pipelines`     | Deal pipelines and their stages, with a `default: true` flag on the default pipeline. |
| `users`         | All users on the account: id, name, role.                             |
| `tags`          | Tags currently in use on the account.                                 |
| `reasons_lost`  | Configured reasons for losing a deal (when enabled).                  |
| `predefined_actions` | Saved action templates — name and a `days` offset for scheduling. |
| `predefined_items`   | Saved deal line-items — name, description, `cost`, `price`.    |
| `schema`        | Custom-field definitions per entity — `name`, `type`, `choices`, and whether each is `mandatory` on create. |
| `account`       | Account metadata: subscription plan, timezone, seat count.            |
| `user`          | The current user's defaults — e.g. `default_deal_commission_percentage`. |

The shape of each entry mirrors what's used elsewhere in the API.
Statuses, lead sources, and call results expose a `system_id` /
`display_name`; reasons lost, predefined actions, and predefined items
expose an `id` / `name`. Users expose `id`, `first_name`, `last_name`,
`role`. Pipelines expose `id`, `name`, `type` (`sales` or `delivery`),
`default`, and nested `stages` — each stage a `{ stage, label }` pair,
where `stage` is the integer you filter and group deals on.

These same custom fields are on
[`describe(entity)`](/mcp/tools/describe/) too — as writable
`custom_fields.<name>` fields with their query types, filter/sort flags,
and dropdown choices, which is the view to use for querying and writing.
The one thing `context().schema` adds is the `mandatory` flag.

## Example

Calling `context()` from the agent returns something like:

```jsonc
{
  "statuses": [
    { "system_id": "lead",     "display_name": "Lead" },
    { "system_id": "customer", "display_name": "Customer" }
  ],
  "pipelines": [
    {
      "id": "65f...",
      "name": "Sales",
      "type": "sales",
      "default": true,
      "stages": [
        { "stage": 10, "label": "Qualified" },
        { "stage": 20, "label": "Demo scheduled" }
      ]
    }
  ],
  "users":              [ { "id": "...", "first_name": "Sam", "last_name": "Lee", "role": "owner" } ],
  "tags":               [ "VIP", "Newsletter" ],
  "reasons_lost":       [ { "id": "...", "name": "Price too high" } ],
  "predefined_actions": [ { "id": "...", "name": "Follow up with [Firstname]", "days": 2 } ],
  "schema":             { "contacts": [{ "name": "Birthday", "type": "anniversary", "choices": [], "mandatory": false }] },
  "account":            { "plan": "Business", "timezone": "Europe/Dublin", "seats": 8 },
  "user":               { "default_deal_commission_percentage": 10 }
}
```

## When the agent should call it

Once per session before the first write, and again after the user
mentions a stage, status, user, or tag that wasn't in the previous
context payload. This reference data changes only when an account
admin edits settings, so there's no need to refresh it every turn.

## Errors

- **Missing server context** — the tool requires a resolved
  account and user. In a properly authorized MCP session this is
  always populated; an error here usually means the OAuth token has
  been revoked or expired.

## Scope

`mcp`. `context` returns account reference data, not records, so it's
available on every authorized MCP session.