Skip to content
Docs menu

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.

View .md

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 (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); 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_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

{ "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.