Skip to main content
Once you’ve connected folk MCP, AI assistants can use these tools to search, create, and manage content in your folk workspace. These tools work seamlessly together through prompts, and their real power comes from combining them. With a single prompt, you can search your workspace, create new contacts from the results, and update fields across multiple records.

​
Workspace

folk_get_current_userRead-onlyIdempotentReturns the identity of the authenticated folk user for this MCP session: their id, email, and fullName. Call once per session when you need to attribute an action to the current user (e.g. assigning a task, filtering by owner). Do not call to look up other workspace members — use the members array from folk_get_workspace_schema instead. Does not return role, permissions, or plan information.
folk_get_workspace_structureRead-onlyRetrieves the complete structure of the folk workspace: groups, entity types per group, native fields (person/company/object), custom field definitions (names, types, allowed values), pipeline views, and workspace members. Call at the start of every fresh session before reading or writing any workspace data — the schema may have changed since the last session (new groups, renamed fields, updated pipeline stages). Do not call again within the same session unless the user explicitly changes the workspace structure. Does not return contact data, notes, or interaction history.

​
Companies

folk_search_companiesRead-onlySearch companies in the folk workspace using one or more filters.Use for:
  • finding a specific company (e.g. “Acme Corp”)
  • filtering companies by native fields, groups, creators, or custom fields
Do not call with an empty filter.Filter shape: { "<fieldName>": { "<operator>": <operand> } }Field categories:
  • Text fields (name, description, industry, emails, phones, urls, addresses, custom fields): operators: eq, not_eq, like, not_like, empty, not_empty
  • Numeric/date fields (fundingRaised, lastFundingDate, createdAt, custom fields): operators: eq, not_eq, gt, lt, empty, not_empty
  • Single and multi select fields (custom fields): operators: in, not_in, empty, not_empty
  • Reference fields (groups, createdBy): operators: in, not_in, all, empty, not_empty
Important operand rules:
  • eq / like / gt / lt → operand is usually a plain string Example: { "name": { "eq": "John Doe" } }
  • empty / not_empty → operand MUST be an empty string Example: { "industry": { "empty": "" } }
  • in / not_in / all → operand MUST be an object with a single attribute being a single string or an array of string Example: { "createdBy": { "in": { "id": "usr_123" } } } OR { "groups": { "in": { "id": ["grp_123"] } } }
  • SingleSelect and multiSelect custom fields → operand is a plain string or array of plain strings (NOT an id object) Examples: { "customFieldValues.grp_xxx.Status": { "in": "Active" } } { "customFieldValues.grp_xxx.Tags": { "in": ["B2C","B2B"] } }
  • Relationships / Assign / Deals custom fields → operand MUST be an object with a single id being a single string or an array of string Examples: { "customFieldValues.grp_xxx.Relationships": { "in": { "id": "per_aaa" } } } { "customFieldValues.grp_xxx.Owner": { "in": { "id": "usr_aaa" } } } { "customFieldValues.grp_xxx.Deals": { "in": { "id": "obj_aaa" } } }
Custom fields: Use key format customFieldValues.<groupId>.<fieldLabel> Example: { "customFieldValues.grp_xxx.Status": { "in": "Active" } }Use combinator for AND/OR logic. Returns paginated company objects. Use folk_get_company if companyId is already known.
folk_get_companyRead-onlyFetch a single company by companyId. Use when you already have a companyId from a previous search_companies call or from another tool response. Do not use to find or look up a company by name, domain, or other attribute — use search_companies instead. Returns the full company object: native fields (name, description, industry, foundationYear, fundingRaised, lastFundingDate, employeeRange), group memberships, and custom field values per group.
folk_create_companyRead-writeCreate a new company in the folk workspace. Provide at least a name to identify the company. Multi-value fields (emails, phones, addresses, urls) accept plain arrays — the first element becomes the primary value. Use groups (array of ) to add the company to one or more groups at creation time. Use customFieldValues to set custom field values, keyed by group id then field name — every group id used there must also be present in groups. Returns the full company object.
folk_update_companyRead-writeDestructiveUpdate an existing company by id. Partial update — omit any field you don’t want to change. Scalar fields (name, description, industry, foundationYear, fundingRaised, lastFundingDate, employeeRange): provide the new value directly. Multi-value fields (emails, phones, addresses, urls) require a prefixed operation param — add/remove will be mutually exclusive to set operation.
  • add* — append values to the existing list (e.g. addEmails: [‘new@acme.com’])
  • remove* — remove specific values from the existing list
  • set* — replace the entire list with the provided values. To add the company to a group, use addGroupIds. Groups cannot be removed via this tool. Use customFieldValues to update custom field values, keyed by group id then field label. Returns only companyId — call get_company if you need the updated full object.

​
People

folk_search_peopleRead-onlySearch people in the folk workspace using one or more filters.Use for:
  • finding a specific person (e.g. “John Doe”)
  • filtering people by native fields, groups, companies, creators, or custom fields
Do not call with an empty filter.Filter shape: { "<fieldName>": { "<operator>": <operand> } }Field categories:
  • Text fields (fullName, firstName, lastName, jobTitle, description, emails, phones, urls, addresses, custom fields): operators: eq, not_eq, like, not_like, empty, not_empty
  • Numeric/date fields (birthday, createdAt, interactionMetadata.workspace.lastInteractedAt, interactionMetadata.user.lastInteractedAt, custom fields): operators: eq, not_eq, gt, lt, empty, not_empty
  • Enum fields (gender): operators: eq, not_eq, empty, not_empty Values: “Male”, “Female”, “Unknown”, “Other” Example: { "gender": { "eq": "Female" } }
  • SingleSelect/MultiSelect fields (custom fields): operators: in, not_in, empty, not_empty
  • Reference fields (groups, companies, createdBy): operators: in, not_in, all, empty, not_empty
Important operand rules:
  • eq / like / gt / lt → operand is usually a plain string Example: { "fullName": { "eq": "John Doe" } }
  • empty / not_empty → operand MUST be an empty string Example: { "jobTitle": { "empty": "" } }
  • in / not_in / all → operand MUST be an object with a single attribute being a single string or an array of string Example: { "createdBy": { "in": { "id": "usr_123" } } } OR { "groups": { "in": { "id": ["grp_123"] } } }
  • SingleSelect and multiSelect custom fields → operand is a plain string or array of plain strings (NOT an id object) Examples: { "customFieldValues.grp_xxx.Status": { "in": "Active" } } { "customFieldValues.grp_xxx.Tags": { "in": ["B2C","B2B"] } }
  • Relationships / Assign / Deals custom fields → operand MUST be an object with a single id being a single string or an array of string Examples: { "customFieldValues.grp_xxx.Relationships": { "in": { "id": "per_aaa" } } } { "customFieldValues.grp_xxx.Owner": { "in": { "id": "usr_aaa" } } } { "customFieldValues.grp_xxx.Deals": { "in": { "id": "obj_aaa" } } }
Custom fields: Use key format customFieldValues.<groupId>.<fieldLabel> Example: { "customFieldValues.grp_xxx.Status": { "in": "Active" } }Use combinator for AND/OR logic. Returns paginated person objects. Use folk_get_person if personId is already known.
folk_get_personRead-onlyFetch a single person by their folk person id and return the full person payload (names, emails, phones, addresses, urls, companies, groups, custom field values, interaction metadata). Use this only when you already have the person id (e.g. from folk_search_people or a previous folk_create_person). Do not use it to look up a person by name or email — that is what folk_search_people is for.
folk_create_personRead-writeCreate a new person in the folk workspace and return the full created person. Provide at least a name (fullName, or firstName/lastName) OR at least one email. For every multi-value field (emails, phones, addresses, urls), the first element is treated as the primary value. companyIds links the person to existing companies (call get_workspace_structure / search to obtain ids). groupIds adds the person to groups at creation. customFieldValues are keyed by group id, then by field name.
folk_update_personRead-writeDestructiveUpdate an existing person in the folk workspace. Only the fields you provide are changed — omitted fields are left untouched. For multi-value fields (emails, phones, addresses, urls, companyIds) use addX / removeX for incremental changes or setX to replace the full list. addGroupIds is additive only (groups are never removed via this tool). customFieldValues are keyed by group id, then by field name.

​
Objects

folk_search_objectsRead-onlySearch objects (e.g. deals) in the folk workspace using one or more filters.Use for:
  • finding a specific object (e.g. “Project Alpha”)
  • filtering objects by name, creation date, creator, or custom fields
Do not call with an empty filter. Use folk_get_workspace_structure first to discover available groupIds and object types.Filter shape: { "<fieldName>": { "<operator>": <operand> } }Field categories:
  • Text fields (name): operators: eq, not_eq, like, not_like, empty, not_empty
  • Date fields (createdAt): operators: eq, not_eq, gt, lt, empty, not_empty
  • Reference fields (createdBy): operators: in, not_in, empty, not_empty
Important operand rules:
  • eq / like / gt / lt → operand is usually a plain string Example: { "name": { "eq": "Project Alpha" } }
  • empty / not_empty → operand MUST be an empty string Example: { "name": { "empty": "" } }
  • in / not_in / all → operand MUST be an object with a single attribute being a single string or an array of string Example: { "createdBy": { "in": { "id": "usr_123" } } } OR { "groups": { "in": { "id": ["grp_123"] } } }
  • SingleSelect and multiSelect custom fields → operand is a plain string or array of plain strings (NOT an id object) Examples: { "customFieldValues.Status": { "in": "Active" } } { "customFieldValues.Tags": { "in": ["B2C","B2B"] } }
  • Relationships / Assign / Deals custom fields → operand MUST be an object with a single id being a single string or an array of string Examples: { "customFieldValues.Relationships": { "in": { "id": "per_aaa" } } } { "customFieldValues.Owner": { "in": { "id": "usr_aaa" } } }
Custom fields: Use key format customFieldValues.<fieldLabel> Example: { "customFieldValues.Status": { "in": "Active" } }Use combinator for AND/OR logic. Returns paginated object payloads with name, people, companies, customFieldValues. Use folk_get_object if objectId is already known.
folk_get_objectRead-onlyFetch a single object (e.g. deal) by its ID within a specific group and object type. Use when you already have an objectId from a previous folk_search_objects or folk_create_object call. Returns the full object: name, people, companies, createdAt, createdBy, customFieldValues.
folk_create_objectRead-writeCreate a new object (e.g. deal) within a specific group and object type in the folk workspace. Use folk_get_workspace_structure first to discover available groupIds and object types. Provide name, and optionally link people and companies by their folk IDs. customFieldValues is a flat record keyed by field name (e.g. { "Status": "Active" }) — no group nesting needed. Returns the full created object.
folk_update_objectRead-writeDestructiveUpdate an existing object (e.g. deal) in the folk workspace. Partial update — omit any field you don’t want to change. name: provide new value to rename. people / companies: providing a list REPLACES all current associations. Omit to leave unchanged. customFieldValues: flat record keyed by field name. Passing null or empty array unsets the value. Returns only objectId — call folk_get_object if you need the updated full object.

​
Notes

folk_search_notesRead-onlySearch notes in the folk workspace.Use for:
  • listing recent notes across the workspace (no filters needed)
  • finding notes attached to a specific contact or company
  • filtering notes by creation date or content
Parameters:
  • entityId (optional): filter by entity. Format per_<uuid> for a person, com_<uuid> for a company, obj_<uuid> for objects.
  • query (optional): full-text search against note content.
  • createdAfter (optional): ISO 8601 timestamp — return only notes created after this date.
  • createdBefore (optional): ISO 8601 timestamp — return only notes created before this date.
  • limit / cursor: pagination.
Returns paginated note objects with nextCursor when more pages exist.
folk_create_noteRead-writeCreate a new note linked to a person or company in the folk workspace.entity.id: required — the entity to attach the note to. Format: per_<uuid> for a person, com_<uuid> for a company and obj_<uuid> for an object . Obtain entity IDs from folk_search_people, folk_search_companies or folk_search_objects. content: required — note body in markdown (max 100 000 chars). visibility: “public” (visible to all workspace members) or “private” (visible only to you). Defaults to “public”. parentNote.id: optional — attach as a reply to an existing note on the same entity.Returns the full created note object.
folk_update_noteRead-writeDestructiveUpdate the content or visibility of an existing note.Partial update — omit any field you do not want to change. noteId: the note to update (format: nte_<uuid>). Obtain from folk_search_notes. content: new markdown body (optional). visibility: “public” or “private” (optional).Returns only noteId. Call folk_search_notes to retrieve the updated note object. Note: only user-authored notes can be updated.

​
Groups

folk_list_groupsRead-onlyList the groups in the folk workspace that the caller can access.Use for:
  • listing the workspace’s groups (no filters needed)
  • retrieving group ids to use with other endpoints, such as listing a group’s custom fields.
Parameters:
  • limit / cursor: pagination.
Returns paginated group objects (id, name, visibility) with nextCursor when more pages exist. Group ids are formatted grp_<uuid>.
folk_create_groupRead-writeCreate a new group in the folk workspace.name: required — the name of the group. visibility: “public” (visible to all workspace members) or “private” (visible only to explicitly added group members).A default “All people” table view is automatically created for the group. Creation is atomic: if the view cannot be created, the group is not created either.Returns the full created group object.
folk_update_groupRead-writeDestructiveUpdate the name and/or visibility of an existing group.Partial update — omit any field you do not want to change. groupId: the group to update (format: grp_<uuid>). Obtain from folk_list_groups. name: new name of the group (optional). visibility: “public” or “private” (optional).Changing visibility resets group membership: all current members are removed and the caller becomes the sole owner.Returns the full updated group object.
folk_list_group_membersRead-onlyIdempotentList the members of a group, paginated. For a public group, this returns every workspace member as they are all members of the group — role defaults to admin unless the member has an explicit role in the group.
folk_add_group_memberRead-writeAdd a workspace member to a group with the given role.
folk_update_group_member_roleRead-writeDestructiveUpdate the role of an existing group member. Fails on a public group, and when the target user is not an explicit member of the group.
folk_remove_group_memberRead-writeDestructiveRemove a member from a group. Fails on a public group, when the target is not a member, or when the target is the group owner.
folk_list_group_custom_fieldsRead-onlyIdempotentReturns the list of the group’s custom fields for an entity type.
folk_get_group_custom_fieldRead-onlyIdempotentFetch a single group custom field by group, entity type, and custom field name. Returns the detailed custom field definition (name, type, options, config) for that entity type. Use folk_list_group_custom_fields if the custom field name isn’t already known.
folk_create_group_custom_fieldRead-writeCreates a new group custom field for an entity type (person, company, or a custom object name).
folk_update_group_custom_fieldRead-writeDestructiveIdempotentUpdates a group custom field: rename it, update its numeric config, or add/update/remove its select options.

​
Interactions

folk_create_interactionRead-writeLog a past interaction (a recorded touchpoint such as a call, meeting, or message) with a person or company.Use for:
  • recording that a conversation or meeting happened (e.g. “Had a coffee with John Doe”)
Only manually logged interactions can be created here. Imported interactions (email, calendar, WhatsApp) sync automatically from connected sources and cannot be created with this tool.Required:
  • entity.id — the person (per_<uuid>) or company (com_<uuid>) the interaction is linked to
  • dateTime — when the interaction happened, as an ISO 8601 timestamp (e.g. “2025-07-17T09:00:00.000Z”)
  • title — short summary of the interaction
  • content — the multi-line body of the interaction
  • activityType — the kind of interaction: a predefined activity (call, meeting, message, coffee, lunch, event, drink), a messaging app (slack, whatsapp, linkedin, telegram, etc.), or a single emoji
Returns the full created logged interaction.
folk_list_past_interactionsRead-onlyList interactions that have already happened for a single person, company, or object.Use for:
  • reviewing the recent communication history with a contact
  • finding an interaction’s id to pass to folk_get_interaction or folk_update_interaction
Provide entityId to scope results (this tool always targets one entity — it cannot search across the whole workspace). Returns both imported interactions (email, calendar, WhatsApp) and manually logged ones. Some content may be hidden depending on the workspace’s interaction privacy rules. The response includes nextCursor when more results are available; pass it back as cursor to fetch the next page.
folk_list_upcoming_interactionsRead-onlyList future-dated interactions for a single person, company, or object.Use for:
  • checking what meetings or events are scheduled with a contact
Provide entityId to scope results (this tool always targets one entity — it cannot search across the whole workspace). Typically returns upcoming calendar events synced from connected sources. Some content may be hidden depending on the workspace’s interaction privacy rules. The response includes nextCursor when more results are available; pass it back as cursor to fetch the next page.
folk_get_interactionRead-onlyFetch a single interaction by its id, including the full email or calendar body when interaction privacy rules allow it.Use this when you already have an interactionId (e.g. from folk_list_past_interactions or folk_list_upcoming_interactions) and need its full details. To find an interaction in the first place, use the list tools instead.Both interactionId and entityId are required, and the entityId must match the entity the interaction is linked to.
folk_update_interactionRead-writeDestructiveUpdate an existing manually logged interaction. Partial update — provide only the fields you want to change (title, content, dateTime, activityType).Only logged interactions (id format lit_<uuid>) can be updated; imported interactions (email, calendar, WhatsApp) cannot. Besides interactionId and entity, at least one updatable field must be provided. Returns the full updated interaction.

​
Tasks

folk_search_tasksRead-onlySearch tasks in the folk workspace with optional attribute filters, paginated via cursor.Use for:
  • listing tasks, optionally filtered by completion state, due date, or attributes
  • finding tasks assigned to specific users, or linked to specific people, companies, or objects
  • finding tasks created, due, or completed within a date range
Filter shape: { "<fieldName>": { "<operator>": <operand> } }Attribute → operator → value table:Operand-shape rules:
  • dueAt / createdAt → operand is a plain date string. Example: { "dueAt": { "gt": "2025-01-01" } }
  • completedAt → empty/not_empty take no operand (task not yet completed / already completed). gt/lt take an ISO 8601 datetime string. Example: { "completedAt": { "not_empty": "" } } Example: { "completedAt": { "gt": "2025-01-01T00:00:00.000Z" } }
  • assigneeUserId → operand is one or more folk-prefixed user ids (usr_...). Obtain ids from folk_get_workspace_structure. Example: { "assigneeUserId": { "in": "usr_7dfc21aa-feb2-40d9-92c9-17ccbe8bbddf" } } Example (exclude): { "assigneeUserId": { "not_in": "usr_7dfc21aa-feb2-40d9-92c9-17ccbe8bbddf" } }
  • entity → operand is one or more folk-prefixed ids, all of the SAME entity type (per_... for people, com_... for companies, obj_... for objects — do not mix types in one filter). Obtain ids from folk_search_people, folk_search_companies, or folk_search_objects. Example: { "entity": { "in": ["per_7dfc21aa-feb2-40d9-92c9-17ccbe8bbddf"] } } Example (exclude): { "entity": { "not_in": ["per_7dfc21aa-feb2-40d9-92c9-17ccbe8bbddf"] } }
Use combinator to control AND/OR logic across multiple filter entries. Omit filter entirely to return every task. onlyAssignedToMe (optional): when true, restricts results to tasks assigned to the current user, combined with any other filters. Returns paginated full task objects: up to limit tasks (default 20, max 100). The response includes nextCursor when more results are available; pass it back as cursor to get the next page. Use folk_get_task if taskId is already known.
folk_create_taskRead-writeCreate a new task linked to a person, company, or object in folk.entity.id format: per_<uuid> | com_<uuid> | obj_<uuid>. Obtain IDs from folk_search_people, folk_search_companies, or folk_search_objects. assignedUsers: accepts user IDs or emails. Defaults to the current user if omitted. Returns the full created task object.
folk_get_taskRead-onlyFetch a single task by its ID. Use when you already have a taskId from a previous folk_search_tasks or folk_create_task call. Do not use to find or look up a task by title, due date, or other attribute — use folk_search_tasks instead. Returns the full task object: title, description, entity, dueAt, dueTime, completedAt, recurrenceFrequency, isPublic, assignedUsers, and createdBy.
folk_update_taskRead-writeDestructiveUpdate an existing task. All fields are optional — omit any to leave unchanged.To update the completion date (to mark a task as done or todo), use folk_update_task_todo_or_done instead.Returns the taskId. Call folk_get_task to retrieve the full updated task.
folk_update_task_todo_or_doneRead-writeMark a task as done or todo. Pass a completedAt datetime to mark as done, or null to mark as todo.Returns the taskId. Call folk_get_task to retrieve the full updated task.