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.
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.
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.
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, custom fields): operators: eq, not_eq, gt, lt, empty, not_empty
  • 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.
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.
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.
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.