Venom People for agents (MCP and REST)
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.
Venom People's tools are on the workspace MCP server: /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).
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(andpeople:writeto 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); 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 |
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 |
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 |
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) 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 |
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): 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) |
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): 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, 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) |
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) |
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) |
people_signal_get, people_signal_run, people_signalsetting_get, people_signalsetting_set |
Signals: 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: 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?) |
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 |
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 |
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 |
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 |
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 |
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 |
See Keep your network warm 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_createand write down promises and next steps: they become the card's open loops. - Search before you add:
people_person_createanswers duplicates, andpeople_person_mergefolds 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
{ "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.