Skip to main content

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.

Endpointhttps://api.onearly.com/mcp
TransportStreamable HTTP, stateless. Send every message as a POST. GET and DELETE return 405.
AuthorisationOAuth 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:

Example: Call a tool with a personal API key
Request
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/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):

Example: Protected resource metadata
Request
GET /.well-known/oauth-protected-resource/mcp HTTP/1.1
Host: api.onearly.com
Response
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"
}
FieldValue
resourcehttps://api.onearly.com/mcp
authorization_serversOnEarly's authorisation server
scopes_supportedopenid, offline_access, mcp:tools
bearer_methods_supportedheader
resource_nameOnEarly

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.

ResponseMeaningWhat 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_tokenThe token was refused.Refresh the token, or authorise again.
403 insufficient_scopeThe token lacks mcp:tools.Authorise again, asking for mcp:tools.
Example: A request without a token
Request
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/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.

AreaToolsAPI key scope
Search and read contentsearch_content, fetch_nodes, read_file, list_node_types, export_contentcontent:read
Saved search viewslist_search_views, save_search_view, delete_search_viewcontent:read
Create contentcreate_node, bulk_insertcontent:create. Not available to group keys.
Your groupsget_my_groups, get_groups_overviewgroup:list
Create a groupcreate_groupgroup:create
Manage groupsupdate_group, invite_to_group, get_group_members, get_group_roles* only
Sharingget_sharing_overviewcontent:read
Sharingshare_contentcontent:share
Services and pathslist_marketplace_services, get_paths* only
Formsget_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 toolsconnector:<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.

ParameterTypeRequiredMeaning
rootContentTypestring or nullYesContent type name of the items to return. null for any type.
searchTermsstring[] or nullYesTerms matched against the title, ignoring case. All must match.
predicatesobject[] or nullYesValue 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).
actorsobject[] or nullYesPeople 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).
includeConnectedNodesbooleanYestrue also returns each match's child content, three levels deep.
sortrelevance, newest, oldest or nullYesnewest puts the most recent first. null means relevance.
limitnumber or nullYesMost 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.

ParameterTypeRequiredMeaning
querystring or nullNoText, meaning or a UUID to match.
contentTypeQuerystring or nullNoUsed as the query when query is null or not sent.
variantTYPE, INSTANCE, ALL or nullNoContent types, content, or both. Default ALL.
ownerany, user, agent, system or nullNoWho owns the content. Default any.
subjectUuidUUID or nullNoThe person the content is about.
contentTypeUuidUUID or nullNoA content type, and content of that type.
includeConnectedNodesbooleanNoInclude linked content. Default true.
includeProvenancebooleanNoInclude where each item came from. Default true.
limitinteger or nullNo1 to 200. Default 50.
offsetinteger or nullNo0 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.

ParameterTypeRequiredMeaning
querystring or nullNoText, meaning or a UUID to match.
variantTYPE, INSTANCE, ALL or nullNoDefault TYPE.
ownerany, user, agent, system or nullNoDefault any.
subjectUuidUUID or nullNoThe person the content is about.
contentTypeUuidUUID or nullNoA content type, and content of that type.
includeSchemabooleanNoInclude each matched type's structure. Default false.
includeExamplesbooleanNoInclude up to three recent pieces of content for each matched type. Default false.
limitinteger or nullNo1 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.

ParameterTypeRequiredMeaning
filestringYesA 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.

ParameterTypeRequiredMeaning
contentTypeUuidsUUID[] or nullYesContent types to include. With exactly one, the CSV has that type's columns.
excludeContentTypeUuidsUUID[] or nullYesContent types to leave out. Can't be combined with contentTypeUuids.
viewActorUuidUUID or nullYesThe group whose content to export.
scopepersonal, allGroups, group or nullYesWhich content to include. group needs viewActorUuid.
searchTermsstring[] or nullYesTerms matched against the title, ignoring case.
sortFieldcreated_at, occurred_at, updated_at or nullYesSort field.
sortDirectionASC, DESC or nullYesSort 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.

ParameterTypeRequiredMeaning
groupUuidstringYesThe 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.

ParameterTypeRequiredMeaning
groupUuidstringYesThe group that will own the view.
namestringYesThe view's name, 1 to 200 characters.
rootContentTypestringYesContent type name of the items the view lists.
searchTermsstring[] or nullYesAs for search_content.
predicatesobject[] or nullYesAs for search_content.
actorsobject[] or nullYesAs for search_content.

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

delete_search_view​

Deletes a saved search view.

ParameterTypeRequiredMeaning
groupUuidstringYesThe group that owns the view.
viewUuidstringYesThe 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.

ParameterTypeRequiredMeaning
clientIdstringNoYour reference for the new item, up to 36 characters. Default node.
variantTYPE or INSTANCENoDefault INSTANCE.
typeNamestring or nullNoNeeded for a TYPE.
valueTypeSTRING, NUMERIC, BOOLEAN, DATE, DATETIME or nullNoThe value type of a TYPE.
typeDescriptionstring or nullNoA description for a TYPE, 1 to 2,000 characters.
contentTypeUuidUUID or nullNoNeeded for an INSTANCE: its content type.
valueobjectNoAt most one of stringValue, numericValue, booleanValue, dateValue and datetimeValue.
subjectUuidUUID or nullNoThe person the content is about.
occurredAtstring or nullNoWhen it happened.
idempotencyKeyUUIDNoSend 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.

ParameterTypeRequiredMeaning
nodesobject[]YesAt least one. Each takes clientId (required), variant, typeName, valueType, typeDescription, contentTypeUuid, contentTypeClientId (a TYPE created earlier in the same call), value, subjectUuid and occurredAt.
edgesobject[]NoLinks to set. Each takes edgeType (CONTAINS, RELATES_TO or INCLUDES), a start (fromClientId or fromContentUuid) and an end (toClientId or toContentUuid).
subjectUuidUUID or nullNoThe person the content is about.
rootClientIdsstring[]NoThe new items that are the roots. Default: the first node.
rootContentUuidsUUID[]NoExisting content to treat as roots.
idempotencyKeyUUIDNoSend 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.

ParameterTypeRequiredMeaning
limitnumber or nullYesMost 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.

ParameterTypeRequiredMeaning
namestringYes2 to 50 characters.
idstringYesThe group's slug: at least 2 lowercase letters, numbers or hyphens.
visibilityPUBLIC, PRIVATE, SECRET or nullYesDefault PRIVATE.
descriptionstring or nullYesUp to 150 characters.

Returns groupActorUuid.

update_group​

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

ParameterTypeRequiredMeaning
groupActorUuidstringYesThe group.
namestring or nullYes2 to 50 characters. null keeps the current name.
visibilityPUBLIC, PRIVATE, SECRET or nullYesnull keeps the current visibility.
descriptionstring or nullYesUp 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.

ParameterTypeRequiredMeaning
groupActorUuidstringYesThe group.
emailstring or nullYesThe invitee's email address. Send this or phone, not both.
phonestring or nullYesThe invitee's phone number, in any format.
firstNamestringYesShown in the invitation. An empty string if unknown.
groupRoleUuidsstring[] or nullYesRoles to give, from get_group_roles. null gives the Member role.
expiresAtdate-time or nullYesWhen 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.

ParameterTypeRequiredMeaning
groupActorUuidstringYesThe group.
limitnumber or nullYesDefault 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.

ParameterTypeRequiredMeaning
groupActorUuidstringYesThe group.
limitnumber or nullYesDefault 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.

ParameterTypeRequiredMeaning
contentUuidstringYesThe content to share.
shareToGroupsstring[]YesGroups whose members all get access. [] for none.
shareToUsersstring[]YesPeople, by userActorUuid. [] for none.
shareToEmailsobject[]YesEach has email, phone, firstName and lastName; all but email can be null. [] for none.
shareToPhonesobject[]YesEach has phone, firstName and lastName; the names can be null. Recipients accept through a texted link. [] for none.
accessLevelviewer, contributor or editorYesWhat recipients can do.
includeDescendantsbooleanYestrue also shares all child content.
messagestring or nullYesA message for the share notification.

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

list_marketplace_services​

Lists the active services in the service catalogue.

ParameterTypeRequiredMeaning
categorystring or nullYesOne 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.

ParameterTypeRequiredMeaning
limitnumber or nullYesDefault 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.

ParameterTypeRequiredMeaning
formLineageUuidstringYesThe 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.

ParameterTypeRequiredMeaning
formLineageUuidstringYesThe form, from get_paths.
previous_field_pathstring or nullYesThe 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.

ParameterTypeRequiredMeaning
formLineageUuidstringYesThe form, from get_paths.
querystringYesA 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.

ParameterTypeRequiredMeaning
formLineageUuidstringYesThe form.
fieldsobjectYesField 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
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/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:

LimitApplies to
120 requests per minuteOne person through one connected app.
300 requests per minuteOne 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/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
}