---
title: Venom People for agents (MCP and REST)
description: Let an agent search the people you know, add people, log interactions, read context cards, and list events and companies, through the workspace MCP server or its REST twin.
section: cloud
order: 161
audience: [user, builder, agent]
sources: [services/nodejs-cloud/lib/people/mcp.ts, services/nodejs-cloud/lib/people/mcp-keepwarm.ts, services/nodejs-cloud/lib/people/tools-keepwarm.ts, services/nodejs-cloud/lib/people/tools.ts, services/nodejs-cloud/lib/people/tools-links.ts, services/nodejs-cloud/lib/people/mcp-links.ts, services/nodejs-cloud/lib/people/auth.ts, services/nodejs-cloud/lib/mcp/rest.ts, services/nodejs-cloud/contracts/openapi/workspace-v1.json, docs/adr/0057-venom-people.md]
features: [cloud.workspace]
---

[Venom People](/docs/cloud/people.md)'s tools are on the [workspace MCP server](/docs/cloud/workspace-mcp.md): `/workspace/mcp/people` lists People's tools alone (connect it as its own server, `venom-people`; the combined
`/workspace/mcp` lists only the cross-product tools, though People's tools run there by name). The same tools answer over REST under `/api/v1/people`
([REST API](/docs/developers/rest.md)).

```sh
claude mcp add --transport http venom-people https://cloud.usevenom.dev/workspace/mcp/people --header "Authorization: Bearer vck_…"
```

## Credentials

People holds each member's own relationships, so the caller must be a member:

- a member's **personal** Venom API key (`vck_…`), or
- an OAuth sign-in for the workspace resource with the scope `people:read` (and `people:write` to change anything).

A team key has no member and is refused in words, as is a service agent an admin scoped to other apps. The agent sees
exactly what the member sees: their own people in full, and people others shared with them without notes, handles,
cards or interactions.

## Tools

| Tool | What it does |
|---|---|
| `people_person_search` | find people by words or a description, blended with meaning over your own people; filters `tag`, `company`, `event`, `circle`, `owner` (`me`, `shared`), and `filter`: the list's URL query for every filter at once, several values each (`country=sg,my&nearby=1&seniority=5,6&warmth=cooling`, see [Filters](/docs/cloud/people.md#filters)); `sort` adds `seniority`, `warmth` and `warming`. Your own people come with their derived fields (seniority, function, sector, country, warmth, outreach, every employer) |
| `people_person_get` | one person: profile, handles, how you met, notes, the context card, recent interactions, relationships and who else knows them; `refresh_card` rebuilds the card first |
| `people_person_create` | add a person (private unless `visibility` says otherwise), with an optional first `interaction`; answers possible duplicates |
| `people_person_update` | change fields, `add_tags`/`remove_tags`, `handles` (replaces them), `profile` (replaces it) or `add_profile` (merges into it), sharing, `archive`, or the derived fields by hand: `seniority` (0–6), `function`, `sector`, `country` (ISO code), `gender`, `personality` (up to 3); `"auto"` gives one back to the rules |
| `people_person_merge` | merge `drop` into `keep` |
| `people_interaction_create` | log met, call, message, meeting, email or note, with `occurred_at`, `channel`, `place`, `event`, and `globe_note` (a note this points at). This is also how an agent adds a note |
| `people_interaction_list` | a person's interactions, newest first; `before` pages |
| `people_relationship_create` | link two of your people: `knows`, `colleague`, `introduced_by`, `reports_to`, `family`, `partner`, `investor_in` or `custom` (with a `label`), optional `since`; see [Connections](/docs/cloud/people-connections.md) |
| `people_relationship_list`, `people_suggestion_list` | a person's links and past employers; suggested links (same company, same event, the named introducer), never saved |
| `people_employment_create`, `people_employment_delete`, `people_employer_set` | link a person to a company with a role and dates; remove it; record your own employers |
| `people_graph_get` | your network as nodes and edges, strongest 300 by default, with derived relationships by `kinds`, `group` hubs and `like` (people like X); see [the graph](/docs/cloud/people-graph.md) |
| `people_link_list`, `people_know_who` | why a person is connected to others (same company with the years, school, event, place, topic from your notes, and more), strongest first with every reason; who you know `at` a company, `from` a school, `in` a place or who `worked_in` a country; see [Relationships](/docs/cloud/people-graph.md#relationships) |
| `people_event_list`, `people_event_create` | events (`around` a date); add one |
| `people_company_list`, `people_company_get` | companies with how many people you may see there now and ever (`sort`: `now` or `ever`); one with its people now and those of yours who worked there before, with when |
| `people_capture_create` | capture people from `text` (a quick note, or vCard text), `image_base64` (a card or badge photo; over 50 KB use `upload_id` from `people_image_prepare`, or `image_url`), `images` (several screenshots, grouped into one draft per person: [Add several people](/docs/cloud/people-capture.md#add-several-people)) or `vcf`: drafts them (with who you already know) or, with `confirm`, saves them with a `met` interaction at the day's event; see [Capture](/docs/cloud/people-capture.md) |
| `people_followup_list` | today's follow-ups: up to five of your people with the reason, the draft and the channel links; `scope` overdue or all adds who is past their cadence |
| `people_followup_draft` | draft a message for a follow-up or a person through your org's gear (under its daily limit), for a `channel`; you never send it |
| `people_followup_done` | `action` done, sent (logs the outbound message), snooze (`days`) or dismiss |
| `people_debrief_run` | events with unrated people; with an `event` its cards, strongest signal first; with `ratings` rate people hot, warm, later or skip |
| `people_circle_list`, `people_circle_update` | circles with cadences and counts (or one person's strength with its reasons); change a circle's cadence or a person's circle and cadence |
| `people_interaction_delete`, `people_relationship_delete` | delete an interaction you logged, remove a relationship between two of your people |
| `people_card_refresh` | rewrite a person's context card now (one call under the daily People AI limit) |
| `people_company_update` | change a company's `name`, `domain`, `location` or `notes` |
| `people_followup_snooze`, `people_followup_dismiss`, `people_followup_update`, `people_followup_send` | snooze a follow-up (`days`), dismiss it, replace its draft `text`, or record that you sent it yourself on a `channel` (Venom sends nothing) |
| `people_person_rate`, `people_person_circle_set` | rate a person hot, warm, later or skip; set their circle and cadence |
| `people_image_list`, `people_image_add`, `people_image_delete` | the images kept with a person ([Several images](/docs/cloud/people-capture.md#several-images)): list for anyone who may see them; add (an `upload_id`, a public `url`, or base64 for small images) and delete for the owner |
| `people_image_prepare` | step 1 of sending a picture or file too big for base64: a one-time upload URL and the `curl -T` line, for an image, a photo, a card to capture or an attachment ([Files and pictures over MCP](/docs/cloud/mcp-files.md)) |
| `people_image_get` | see an image kept with a person, or a person's photo, as a picture the model sees, with a short-lived download URL |
| `people_attachment_list`, `people_attachment_get`, `people_attachment_add`, `people_attachment_update`, `people_attachment_delete` | the images, files and links kept with a person ([Attachments on a person](/docs/cloud/people-attachments.md)): list and read (a file up to 1.5 MB as base64 with `include_bytes`) for anyone who may see them; add a link (`url`) or a file (`upload_id` after `people_image_prepare`, `file_url`, or `file_base64` with `file_name`; type read from the bytes), rename, note and delete for the owner |
| `people_image_read` | read some or all of a person's kept images as that person, in calls of up to 8, into suggestions (changed role, company or location; new phones, emails, handles, tags; profile sections such as "+ 3 jobs"); saves nothing unless `apply: "all"` ([Enrich a person from snapshots](/docs/cloud/people-capture.md#enrich-a-person-from-snapshots), [The profile](/docs/cloud/people-capture.md#the-profile)) |
| `people_person_enrich`, `people_enrichment_get`, `people_enrichment_apply`, `people_enrichment_dismiss` | ask the providers your organisation picked for public facts and photos about one of your people (official APIs only), read the numbered suggestions with their sources, apply `picks` or `apply: "all"` (and a `photo`), or dismiss them; off until an owner or admin turns it on ([Enrich people](/docs/cloud/people-enrichment.md)) |
| `people_enrichment_run` | enrich up to 200 of your `people` in a run; call again with `run` until it is done (progress, cost, the daily cap) |
| `people_enricher_get`, `people_enricher_set` | the organisation's enrichment switch, providers in order (with what each is sent), daily cap and PDL and Apollo keys (owners and admins change them) |
| `people_person_photo_set` | set a person's photo from an `upload_id`, a public `url` (or a photo candidate from their enrichment) or a small base64 image |
| `people_trip_list`, `people_trip_create`, `people_trip_delete` | your upcoming trips (`city`, `starts_on`, `ends_on`): the picks favour people in the city you travel to |
| `people_recall_ask` | "who do I know who…", answered from your own people with numbered citations |
| `people_today_find` | ask for who you want (`request`): up to 20 of your own people with a why line from their record; at most three model calls under the daily People AI limit, a word search without a gear or at the limit ([Ask for who you want](/docs/cloud/people-keep-warm.md#ask-for-who-you-want)) |
| `people_brief_list`, `people_brief_create`, `people_brief_update`, `people_brief_delete` | your standing briefs (up to ten): saved requests whose matches come up in the daily picks; `paused` stops one |
| `people_downvote_list`, `people_downvote_set`, `people_downvote_delete` | "not yet" on one of your people (`reason` not_now, not_relevant, in_touch or other; `days`): left out of picks and finds until then; delete is the undo ([Not yet](/docs/cloud/people-keep-warm.md#not-yet)) |
| `people_signal_get`, `people_signal_run`, `people_signalsetting_get`, `people_signalsetting_set` | [Signals](/docs/cloud/people-signals.md): one of your own people's call (engage, progress, hold, drop or insufficient data), strengths, weaknesses and a score per indicator; assess one now; the organisation's switch, gear and caps (owners and admins) |
| `people_aisetting_get`, `people_aisetting_set` | [People's daily AI limit](/docs/cloud/people.md#ai-and-limits): the limit and today's spend against it and each feature's own daily cap; set it (owners and admins, $0 to $100; not an agent acting for one) |
| `people_todaysetting_get`, `people_todaysetting_set` | your Today settings: `count`, `weights` per reason, `downvote_days`, `exclude_tags`, `exclude_circles`, `exclude_companies`, `channels`, `note_steps` |
| `people_todaynote_create` | save how reaching out went (`text`, `outcome`, `channel`, `followup`) as an interaction on the person, then one bounded model call (or the rules) picks the next step; low-risk steps apply with your `note_steps` setting auto ([How did it go?](/docs/cloud/people-keep-warm.md#how-did-it-go)) |
| `people_nextstep_get`, `people_nextstep_apply`, `people_nextstep_undo` | a note's next step: read it (by `step` or `person`), apply it or change its `action` and `when`, undo it |
| `people_person_share` | share one person (`person`), several (`people`) or a whole `circle` with a team or the org, or take sharing back (`visibility` private); see [the network](/docs/cloud/people-network.md) |
| `people_person_bulk_update` | change up to 10,000 of your `people` at once, in one transaction: `add_tags`, `remove_tags`, `circle` (null for none), `cadence_days` (1 to 3650, null for the circle's), `company`, `location` (empty clears), `seniority`, `country`, `gender`, `sector` (a value, null, or `"auto"`), or `archive` (to the trash) and `restore` (each on its own). It changes everyone it may and names who it skipped: people shared with you, and shared contacts your role can't change. REST: `POST /api/v1/people/bulk`; see [Select and edit many](/docs/cloud/people.md#select-and-edit-many) |
| `people_reach_search` | whom to contact about a topic in a territory: your own people ranked by fit, seniority and reachability, each with a route (`open-loop`, `direct`, `rewarm`, `intro`, `cold`), a one-line why and, for an intro, the introducer; `companies: true` rolls the result up by company. Read only, no model call. REST: `GET /api/v1/people/reach`; see [Reach](/docs/cloud/people-reach.md) |
| `people_overnight_list`, `people_overnight_update`, `people_overnight_run`, `people_view_update` | the overnight queue: the people your nightly Reach views picked, each with route, reason and draft; `edit`, `sent` (logged once), `skip`, `not_yet` or `redraft` a pick; run the night now; switch a saved Reach view to nightly with its count. Venom never sends; see [the overnight queue](/docs/cloud/people-overnight.md) |
| `people_network_search` | "who knows someone at …": your people and what colleagues shared, grouped by real person, each with the warm-intro paths ranked by the colleague's strength |
| `people_intro_path` | the warm-intro paths to one person you may see and, for one of your own people, your own contacts who could introduce you (`connectors`) |
| `people_intro_request` | ask the colleague who knows a shared person for an intro (lands in their bell); `message` says why, optional `blurb` is a note they can forward |
| `people_intro_list`, `people_intro_respond` | intro requests asked of you and sent by you; accept (optionally `draft`, one call under the daily limit), decline, `draft`, `cancel` or `introduced` (either side, once accepted). Venom never sends the intro |
| `people_introask_list`, `people_introask_create`, `people_introask_update`, `people_introsetting_set` | your own intro asks: ask one of your contacts to introduce you, with a drafted ask and a note to forward, tracked from draft to introduced, with nudges. Never sent by Venom. See [Ask for an intro](/docs/cloud/people-intros.md) |
| `people_import_run` | import a file's text (Google, HubSpot, Pipedrive or LinkedIn CSV, vCard, a WhatsApp chat, Telegram's result.json): read-only until `confirm`, at most 500 people per call; see [Import](/docs/cloud/people-import.md) |

See [Keep your network warm](/docs/cloud/people-keep-warm.md) for what each does. `people_interaction_create` takes `direction`
(`in`, `out`, `both`) for reciprocity.

Answers are short markdown; pass `format: "json"` for `structuredContent` (the REST twin always answers JSON). Ids
are UUIDs; interaction lines carry their citation tag (`[i:1a2b3c4d]`), the same one the context card uses.

## Rules for agents

- Log every touch with `people_interaction_create` and write down promises and next steps: they become the card's
  open loops.
- Search before you add: `people_person_create` answers duplicates, and `people_person_merge` folds them.
- Never send a message on the user's behalf. Draft it and let the user send it from their own app.
- The context card costs one model call through the organisation's gear, within its daily People limit; don't refresh
  it in a loop.

## Example

```json
{ "name": "people_person_create", "arguments": {
  "name": "Sarah Chen", "role": "Founder", "company": "FrostCo", "location": "Jakarta", "tags": ["cold-storage"],
  "handles": [{ "kind": "whatsapp", "value": "+62 811 222 333" }],
  "interaction": { "kind": "met", "summary": "Booth at GPU Summit. Wants GPU pricing for a warehouse cluster; I promised the deck by Friday." }
} }
```

Over REST: `POST /api/v1/people` with the same fields, then `POST /api/v1/people/{person}/interactions`.
