# MCP server

OnEarly runs a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, so AI assistants and other MCP clients can search, read and add to OnEarly content on a person's behalf. Everything a client does through it is limited to what that person, or that group, can already do.

| | |
|---|---|
| Endpoint | `https://api.onearly.com/mcp` |
| Transport | Streamable HTTP, stateless. Send every message as a `POST`. `GET` and `DELETE` return `405`. |
| Authorisation | OAuth 2.0 (connected apps) or an API key |

The endpoint is the same for every region. You don't need to handle [wrong-region](/errors/wrong-region) responses here.

## Connecting

### With OAuth (connected apps)

Add `https://api.onearly.com/mcp` as a remote MCP server in your client. A client that supports MCP authorisation will open OnEarly's sign-in, ask the person to approve it, and then appear under **Account → Connected apps**. See [Connected apps](./authentication.md#connected-apps-oauth) for the flow and the consent scopes.

### With a personal API key

For a client that takes a fixed header, create a key under **Account → Developer → Personal API keys** and send it as a bearer token:

**Example: Call a tool with a personal API key**

Request:

```http
POST /mcp HTTP/1.1
Host: api.onearly.com
Authorization: Bearer oe_sk_live_au_3f9a1c0e7b2d4a6f8e1c3b5d7a9f0e2c
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_my_groups",
    "arguments": {
      "limit": null
    }
  }
}
```

Response:

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"groups\":[{\"groupActorUuid\":\"6d2f8a14-3b9e-4c57-a0d1-8e4b2c7f9a35\",\"name\":\"Example Physio\",\"id\":\"example-physio\",\"visibility\":\"PRIVATE\"},{\"groupActorUuid\":\"b81c5e07-92da-4f3b-8c6e-1a0d4f7b2e96\",\"name\":\"Riverside Walking Club\",\"id\":\"riverside-walking\",\"visibility\":\"PUBLIC\"}],\"totalCount\":2}"
      }
    ],
    "structuredContent": {
      "groups": [
        {
          "groupActorUuid": "6d2f8a14-3b9e-4c57-a0d1-8e4b2c7f9a35",
          "name": "Example Physio",
          "id": "example-physio",
          "visibility": "PRIVATE"
        },
        {
          "groupActorUuid": "b81c5e07-92da-4f3b-8c6e-1a0d4f7b2e96",
          "name": "Riverside Walking Club",
          "id": "riverside-walking",
          "visibility": "PUBLIC"
        }
      ],
      "totalCount": 2
    }
  }
}
```

The same page shows your MCP address and a configuration you can paste into supported clients. The key's [scopes](./authentication.md#scopes) decide which tools it can use.

Group API keys are accepted too, and act as the group.

## Authorisation

The server describes itself with OAuth protected resource metadata ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)):

**Example: Protected resource metadata**

Request:

```http
GET /.well-known/oauth-protected-resource/mcp HTTP/1.1
Host: api.onearly.com
```

Response:

```http
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: public, max-age=3600

{
  "resource": "https://api.onearly.com/mcp",
  "authorization_servers": [
    "https://auth.onearly.com"
  ],
  "scopes_supported": [
    "openid",
    "offline_access",
    "mcp:tools"
  ],
  "bearer_methods_supported": [
    "header"
  ],
  "resource_name": "OnEarly"
}
```

| Field | Value |
|-------|-------|
| `resource` | `https://api.onearly.com/mcp` |
| `authorization_servers` | OnEarly's authorisation server |
| `scopes_supported` | `openid`, `offline_access`, `mcp:tools` |
| `bearer_methods_supported` | `header` |
| `resource_name` | `OnEarly` |

An OAuth access token is accepted only if it was issued **for this resource** (its audience is `https://api.onearly.com/mcp`) and carries the **`mcp:tools`** scope.

| Response | Meaning | What to do |
|----------|---------|-----------|
| `401` with `WWW-Authenticate: Bearer … resource_metadata="…", scope="mcp:tools offline_access"` | No token, or the token isn't valid here. | Start or repeat the OAuth flow using the metadata link. |
| `401 invalid_token` | The token was refused. | Refresh the token, or authorise again. |
| `403 insufficient_scope` | The token lacks `mcp:tools`. | Authorise again, asking for `mcp:tools`. |

**Example: A request without a token**

Request:

```http
POST /mcp HTTP/1.1
Host: api.onearly.com
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
```

Response:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.onearly.com/.well-known/oauth-protected-resource/mcp", scope="mcp:tools offline_access"
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "authentication required"
  },
  "id": null
}
```

## Tools

Each tool advertises that it needs the `mcp:tools` OAuth scope. With an API key, only the tools its [scopes](./authentication.md#scopes) cover are listed and callable. A key with `*` sees every tool its account or group can use.

| Area | Tools | API key scope |
|------|-------|---------------|
| Search and read content | `search_content`, `fetch_nodes`, `read_file`, `list_node_types`, `export_content` | `content:read` |
| Saved search views | `list_search_views`, `save_search_view`, `delete_search_view` | `content:read` |
| Create content | `create_node`, `bulk_insert` | `content:create`. Not available to group keys. |
| Your groups | `get_my_groups`, `get_groups_overview` | `group:list` |
| Create a group | `create_group` | `group:create` |
| Manage groups | `update_group`, `invite_to_group`, `get_group_members`, `get_group_roles` | `*` only |
| Sharing | `get_sharing_overview` | `content:read` |
| Sharing | `share_content` | `content:share` |
| Services and paths | `list_marketplace_services`, `get_paths` | `*` only |
| Forms | `get_forms_overview`, `get_form_state`, `get_next_form_field`, `search_for_form_field`, `set_form_field_values` | `*` only |
| Connected accounts | `<connector>__<tool>`, for example a connected mailbox's tools | `connector:<connector-id>:tool:<tool>` |

**`*` only** means no narrower scope covers the tool: only a key with full access can use it.

Connected-account tools appear only for the connectors the caller can use: a person's own and those of groups they administer, or a group key's own group. See [Group connectors](/features/connectors-and-connected-apps#group-connectors). Their names start with the connector's name and two underscores. Their parameters are the connected service's own.

A key that calls a tool outside its scopes gets an error naming the scope it needs.

### Tool reference

Every built-in tool returns a JSON object, both as structured content and as a text block. A parameter marked **Yes** must be sent. Where its type allows `null`, send `null` to use the default.

#### `search_content`

Searches content you can read by type, title, values and the people linked to it.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `rootContentType` | string or `null` | Yes | Content type name of the items to return. `null` for any type. |
| `searchTerms` | string[] or `null` | Yes | Terms matched against the title, ignoring case. All must match. |
| `predicates` | object[] or `null` | Yes | Value filters, all of which must match. Each has `pathTypeNames` (1 to 8 content type names, walking down from the item), `op` (`exists`, `eq`, `contains`, `gte` or `lte`), `valueType` (`STRING`, `NUMERIC`, `BOOLEAN`, `DATE` or `DATETIME`, or `null` for `STRING`) and `value` (text, or `null` for `exists`). |
| `actors` | object[] or `null` | Yes | People filters, all of which must match. Each has `edgeTypes` (one or more of `AUTHORED_BY`, `SHARED_WITH` and `SUBJECT_OF`) and `query` (an email address, or part of a name or phone number). |
| `includeConnectedNodes` | boolean | Yes | `true` also returns each match's child content, three levels deep. |
| `sort` | `relevance`, `newest`, `oldest` or `null` | Yes | `newest` puts the most recent first. `null` means `relevance`. |
| `limit` | number or `null` | Yes | Most items to return. Default 20, at most 100. |

Returns `totalMatches`, `returnedRoots`, `rootContentUuids`, `sort`, `nodes` and `edges`.

#### `fetch_nodes`

Lists content you can read, with its owner, subject, type, links and where it came from.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `query` | string or `null` | No | Text, meaning or a UUID to match. |
| `contentTypeQuery` | string or `null` | No | Used as the query when `query` is `null` or not sent. |
| `variant` | `TYPE`, `INSTANCE`, `ALL` or `null` | No | Content types, content, or both. Default `ALL`. |
| `owner` | `any`, `user`, `agent`, `system` or `null` | No | Who owns the content. Default `any`. |
| `subjectUuid` | UUID or `null` | No | The person the content is about. |
| `contentTypeUuid` | UUID or `null` | No | A content type, and content of that type. |
| `includeConnectedNodes` | boolean | No | Include linked content. Default `true`. |
| `includeProvenance` | boolean | No | Include where each item came from. Default `true`. |
| `limit` | integer or `null` | No | 1 to 200. Default 50. |
| `offset` | integer or `null` | No | 0 to 10,000. Default 0. |

Returns `nodes`, `edges`, `provenanceLinks`, their totals, and `pagination` (`offset`, `limit`, `totalRootMatches`, `hasMore`, `nextOffset` and more). `semanticStatus` and `semanticAvailable` say whether search by meaning ran.

#### `list_node_types`

Lists content types, or content, you can read.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `query` | string or `null` | No | Text, meaning or a UUID to match. |
| `variant` | `TYPE`, `INSTANCE`, `ALL` or `null` | No | Default `TYPE`. |
| `owner` | `any`, `user`, `agent`, `system` or `null` | No | Default `any`. |
| `subjectUuid` | UUID or `null` | No | The person the content is about. |
| `contentTypeUuid` | UUID or `null` | No | A content type, and content of that type. |
| `includeSchema` | boolean | No | Include each matched type's structure. Default `false`. |
| `includeExamples` | boolean | No | Include up to three recent pieces of content for each matched type. Default `false`. |
| `limit` | integer or `null` | No | 1 to 200. Default 50. |

Returns `total`, `nodes`, the filters used, `searchMode`, `semanticStatus` and `semanticAvailable`.

#### `read_file`

Reads a file you can open. Files over 10 MB are refused, and so are files that aren't images, PDFs or text.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `file` | string | Yes | A file's content UUID, or an OnEarly download URL ending in one. |

Returns `fileContentUuid`, `name`, `mimeType` and `fileSize`. An image also comes back as an image. A PDF or text file adds `text`, cut at 200,000 characters, and `truncated`.

#### `export_content`

Exports content you can read as CSV. It takes at most 2,000 rows.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `contentTypeUuids` | UUID[] or `null` | Yes | Content types to include. With exactly one, the CSV has that type's columns. |
| `excludeContentTypeUuids` | UUID[] or `null` | Yes | Content types to leave out. Can't be combined with `contentTypeUuids`. |
| `viewActorUuid` | UUID or `null` | Yes | The group whose content to export. |
| `scope` | `personal`, `allGroups`, `group` or `null` | Yes | Which content to include. `group` needs `viewActorUuid`. |
| `searchTerms` | string[] or `null` | Yes | Terms matched against the title, ignoring case. |
| `sortField` | `created_at`, `occurred_at`, `updated_at` or `null` | Yes | Sort field. |
| `sortDirection` | `ASC`, `DESC` or `null` | Yes | Sort direction. |

Returns `shape`, `rowCount`, `returnedRows`, `truncated` and `csv`. The CSV stops at 200,000 characters; `truncated` is `true` when rows were left out.

#### `list_search_views`

Lists a group's saved search views.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `groupUuid` | string | Yes | The group. |

Returns `text`, a JSON string with `totalViews` and `views[]`, each with `viewUuid`, `name`, `contentTypeUuids` and `savedSearch`.

#### `save_search_view`

Saves a search as a view in a group's menu. The view runs the search again each time it opens. You must be an admin of the group.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `groupUuid` | string | Yes | The group that will own the view. |
| `name` | string | Yes | The view's name, 1 to 200 characters. |
| `rootContentType` | string | Yes | Content type name of the items the view lists. |
| `searchTerms` | string[] or `null` | Yes | As for `search_content`. |
| `predicates` | object[] or `null` | Yes | As for `search_content`. |
| `actors` | object[] or `null` | Yes | As for `search_content`. |

Returns `text`, a JSON string with `viewUuid`, `name`, `rootContentType` and `savedSearch`.

#### `delete_search_view`

Deletes a saved search view.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `groupUuid` | string | Yes | The group that owns the view. |
| `viewUuid` | string | Yes | The view, from `list_search_views` or `save_search_view`. |

Returns `text`, a JSON string with `deleted` and `viewUuid`.

#### `create_node`

Creates one content type or one piece of content, as you.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `clientId` | string | No | Your reference for the new item, up to 36 characters. Default `node`. |
| `variant` | `TYPE` or `INSTANCE` | No | Default `INSTANCE`. |
| `typeName` | string or `null` | No | Needed for a `TYPE`. |
| `valueType` | `STRING`, `NUMERIC`, `BOOLEAN`, `DATE`, `DATETIME` or `null` | No | The value type of a `TYPE`. |
| `typeDescription` | string or `null` | No | A description for a `TYPE`, 1 to 2,000 characters. |
| `contentTypeUuid` | UUID or `null` | No | Needed for an `INSTANCE`: its content type. |
| `value` | object | No | At most one of `stringValue`, `numericValue`, `booleanValue`, `dateValue` and `datetimeValue`. |
| `subjectUuid` | UUID or `null` | No | The person the content is about. |
| `occurredAt` | string or `null` | No | When it happened. |
| `idempotencyKey` | UUID | No | Send the same UUID when you retry, so the content isn't created twice. |

Returns `clientIdMap`: for each `clientId`, the new content's `uuid` and `lineageUuid`.

#### `bulk_insert`

Creates several content types, pieces of content and links in one call, as you.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `nodes` | object[] | Yes | At least one. Each takes `clientId` (required), `variant`, `typeName`, `valueType`, `typeDescription`, `contentTypeUuid`, `contentTypeClientId` (a `TYPE` created earlier in the same call), `value`, `subjectUuid` and `occurredAt`. |
| `edges` | object[] | No | Links to set. Each takes `edgeType` (`CONTAINS`, `RELATES_TO` or `INCLUDES`), a start (`fromClientId` or `fromContentUuid`) and an end (`toClientId` or `toContentUuid`). |
| `subjectUuid` | UUID or `null` | No | The person the content is about. |
| `rootClientIds` | string[] | No | The new items that are the roots. Default: the first node. |
| `rootContentUuids` | UUID[] | No | Existing content to treat as roots. |
| `idempotencyKey` | UUID | No | Send the same UUID when you retry, so nothing is created twice. |

Returns `clientIdMap`: for each `clientId`, the new content's `uuid` and `lineageUuid`.

#### `get_my_groups`

Lists the groups you belong to.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `limit` | number or `null` | Yes | Most groups to return. Default 10, at most 50. |

Returns `groups[]`, each with `groupActorUuid`, `name`, `id` (the group's slug) and `visibility`, and `totalCount`.

#### `get_groups_overview`

Explains groups and the group tools. No parameters. Returns `text`.

#### `create_group`

Creates a group. You become its Admin.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `name` | string | Yes | 2 to 50 characters. |
| `id` | string | Yes | The group's slug: at least 2 lowercase letters, numbers or hyphens. |
| `visibility` | `PUBLIC`, `PRIVATE`, `SECRET` or `null` | Yes | Default `PRIVATE`. |
| `description` | string or `null` | Yes | Up to 150 characters. |

Returns `groupActorUuid`.

#### `update_group`

Changes a group's name, visibility or description. Needs the group's `manage-group` permission.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `groupActorUuid` | string | Yes | The group. |
| `name` | string or `null` | Yes | 2 to 50 characters. `null` keeps the current name. |
| `visibility` | `PUBLIC`, `PRIVATE`, `SECRET` or `null` | Yes | `null` keeps the current visibility. |
| `description` | string or `null` | Yes | Up to 150 characters. `null` keeps the current description. |

Send at least one change. Returns `groupActorUuid`, `name` and `visibility`.

#### `invite_to_group`

Invites someone to a group by email or phone. Needs the group's `manage-group-members` permission.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `groupActorUuid` | string | Yes | The group. |
| `email` | string or `null` | Yes | The invitee's email address. Send this or `phone`, not both. |
| `phone` | string or `null` | Yes | The invitee's phone number, in any format. |
| `firstName` | string | Yes | Shown in the invitation. An empty string if unknown. |
| `groupRoleUuids` | string[] or `null` | Yes | Roles to give, from `get_group_roles`. `null` gives the Member role. |
| `expiresAt` | date-time or `null` | Yes | When the invitation expires. `null` gives 30 days. |

Returns `inviteUuid`, `status`, `groupActorUuid`, `groupRoleUuids`, `email` and `phoneNumber`. `email` and `phoneNumber` are `null` unless you may see them.

#### `get_group_members`

Lists a group's members and their roles.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `groupActorUuid` | string | Yes | The group. |
| `limit` | number or `null` | Yes | Default 20, at most 100. |

Returns `members[]`, each with `userActorUuid`, `name`, `roles` and, if you may see it, `email`, and `totalCount`.

#### `get_group_roles`

Lists a group's roles. You must be a member of the group.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `groupActorUuid` | string | Yes | The group. |
| `limit` | number or `null` | Yes | Default 20, at most 50. |

Returns `roles[]`, each with `uuid`, `name`, `description` and `immutable`, and `totalCount`.

#### `get_sharing_overview`

Explains sharing and the sharing tool. No parameters. Returns `text`.

#### `share_content`

Shares content with groups, people, email addresses or phone numbers. Send at least one recipient.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `contentUuid` | string | Yes | The content to share. |
| `shareToGroups` | string[] | Yes | Groups whose members all get access. `[]` for none. |
| `shareToUsers` | string[] | Yes | People, by `userActorUuid`. `[]` for none. |
| `shareToEmails` | object[] | Yes | Each has `email`, `phone`, `firstName` and `lastName`; all but `email` can be `null`. `[]` for none. |
| `shareToPhones` | object[] | Yes | Each has `phone`, `firstName` and `lastName`; the names can be `null`. Recipients accept through a texted link. `[]` for none. |
| `accessLevel` | `viewer`, `contributor` or `editor` | Yes | What recipients can do. |
| `includeDescendants` | boolean | Yes | `true` also shares all child content. |
| `message` | string or `null` | Yes | A message for the share notification. |

Returns `successCount`, `failureCount` and `results[]`, one per recipient.

#### `list_marketplace_services`

Lists the active services in the service catalogue.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `category` | string or `null` | Yes | One exact category. `null` for every category. |

Returns `count` and `services[]`, each with `slug`, `title`, `description` and `category`.

#### `get_paths`

Lists your paths, with their steps and forms in order.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `limit` | number or `null` | Yes | Default 20. |

Returns `paths[]`, each with `pathLineageUuid`, `title`, `description` and `steps`. A step lists its `forms`, each with `formLineageUuid`, `formName`, `required` and `status`.

#### `get_forms_overview`

Explains forms and the form tools. No parameters. Returns `text`.

#### `get_form_state`

Shows how much of a form is filled in.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `formLineageUuid` | string | Yes | The form, from `get_paths`. |

Returns `formLineageUuid`, `completionPercentage`, `filledFieldCount` and `totalFieldCount`.

#### `get_next_form_field`

Gets the next field that isn't filled in. Fields hidden by the form's conditions are skipped.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `formLineageUuid` | string | Yes | The form, from `get_paths`. |
| `previous_field_path` | string or `null` | Yes | The last field filled. `null` gets the first unfilled field. |

Returns `hasNextField`, `field`, any `aiFieldSuggestions`, and the form's progress. When `hasNextField` is `false`, `message` says why.

#### `search_for_form_field`

Finds a form's fields by keyword or question.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `formLineageUuid` | string | Yes | The form, from `get_paths`. |
| `query` | string | Yes | A keyword such as `address`, or a question. |

Returns `query`, `matchCount` and `matches[]`.

#### `set_form_field_values`

Fills in one or more fields of a form.

| Parameter | Type | Required | Meaning |
|-----------|------|----------|---------|
| `formLineageUuid` | string | Yes | The form. |
| `fields` | object | Yes | Field paths mapped to values. For a choice field, use one of its `enumValues` exactly. |

Returns `success`, `message` and `updatedFields`.

**Example: Create a group through a connected app**

A key with scopes needs group:create for this tool. An OAuth token needs mcp:tools.

Request:

```http
POST /mcp HTTP/1.1
Host: api.onearly.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImV4YW1wbGUifQ.eyJzdWIiOiJleGFtcGxlIn0.c2lnbmF0dXJl
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_group",
    "arguments": {
      "name": "Example Physio Team",
      "id": "example-physio-team",
      "visibility": null,
      "description": null
    }
  }
}
```

Response:

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"groupActorUuid\":\"e47a9c21-5d8b-4f06-b3e2-9c1a7d5f0b84\"}"
      }
    ],
    "structuredContent": {
      "groupActorUuid": "e47a9c21-5d8b-4f06-b3e2-9c1a7d5f0b84"
    }
  }
}
```

## Rate limits

Connected apps (OAuth tokens) are limited per person:

| Limit | Applies to |
|-------|-----------|
| 120 requests per minute | One person through one connected app. |
| 300 requests per minute | One person across all their connected apps. |

Requests made with an API key don't count towards these limits.

A limited request returns HTTP `429` with a `Retry-After` header and the JSON-RPC error `{"code": -32000, "message": "rate limited; retry later"}`. Wait for `Retry-After` before sending more.

**Example: A rate-limited request**

Response:

```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 12
Cache-Control: no-store

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "rate limited; retry later"
  },
  "id": null
}
```

Source: https://docs.onearly.com/api/mcp/
