MCP server
OnEarly runs a Model Context Protocol (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 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 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:
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
}
}
}
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 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):
GET /.well-known/oauth-protected-resource/mcp HTTP/1.1
Host: api.onearly.com
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. |
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"
}
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 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. 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.
A key with scopes needs group:create for this tool. An OAuth token needs mcp:tools.
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
}
}
}
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.
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
}