# Modem — how to use (mcp.ai)

Connect your Modem account and use 30 tools for analytics straight from your AI agent. Connect with your own API key. Modem turns customer conversations into structured topics, people, and company insights for analysis and workflow automation.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_modem?ms=1787295720000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `modem_add_people_to_company`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/modem`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/modem/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/modem/add/people/to/company` — Associate one or more existing people with an existing company. People already associated with the company are reported as skipped. This changes company membership, and the approved API surface has no
  - body: { company_id: string, person_ids: string[], idempotency_key?: string }
- `POST https://api.mcp.ai/api/modem/create/companies` — Create one to 50 companies in one batch. Each item succeeds or fails independently; use a one-item array to create one company.
  - body: { companies: object[], idempotency_key?: string }
- `POST https://api.mcp.ai/api/modem/create/people` — Create one to 50 people in one batch. Each item succeeds or fails independently; use a one-item array to create one person.
  - body: { people: object[], idempotency_key?: string }
- `POST https://api.mcp.ai/api/modem/get/channel` — Get one channel's source details, connection state, context, timestamps, and message count by UUID.
  - body: { channel_id: string }
- `POST https://api.mcp.ai/api/modem/get/company` — Get one company's core details, connection values, domain, logo, and VIP status by decimal ID.
  - body: { company_id: string }
- `POST https://api.mcp.ai/api/modem/get/company/activity` — Get one company's message count, weekly activity series, and source-level message breakdown.
  - body: { company_id: string }
- `POST https://api.mcp.ai/api/modem/get/company/history` — Get up to 50 company audit records plus merge history. The API reports the total audit count but exposes no cursor or page parameter, so this tool cannot retrieve records beyond the requested limit.
  - body: { limit?: integer, changed_by?: string[], company_id: string }
- `POST https://api.mcp.ai/api/modem/get/company/identities` — Get external platform identities linked to one company by Modem's identify operation.
  - body: { company_id: string }
- `POST https://api.mcp.ai/api/modem/get/current/organization` — Return the organization selected by the connected API key. Use this as an authentication smoke test and to confirm the active tenant; it returns no member, credential, or plan details.
- `POST https://api.mcp.ai/api/modem/get/person` — Get one person's complete profile, including company, connections, tags, sources, timestamps, identities, and message activity aggregates.
  - body: { person_id: string }
- `POST https://api.mcp.ai/api/modem/get/person/history` — Get up to 50 person audit records plus merge history. The API reports the total audit count but exposes no cursor or page parameter, so this tool cannot retrieve records beyond the requested limit.
  - body: { limit?: integer, person_id: string, changed_by?: string[] }
- `POST https://api.mcp.ai/api/modem/get/person/identities` — Get all external platform identities linked to one person.
  - body: { person_id: string }
- `POST https://api.mcp.ai/api/modem/get/person/source/stats` — Get one person's message counts broken down by source platform.
  - body: { person_id: string }
- `POST https://api.mcp.ai/api/modem/get/topic` — Get one topic's complete details, including its summary, classification, lifecycle, priority, keywords, time range, archive state, and event count.
  - body: { topic_id: string }
- `POST https://api.mcp.ai/api/modem/get/topic/groups` — Get every message group assigned to one topic in ascending or descending group-time order. Modem does not paginate or limit this endpoint, so topics with many deeply nested messages can return a large
  - body: { order?: string, topic_id: string }
- `POST https://api.mcp.ai/api/modem/get/topic/history` — Get up to 50 topic audit records plus action and merge history. The API reports the total audit count but exposes no cursor or page parameter, so this tool cannot retrieve audit records beyond the req
  - body: { limit?: integer, topic_id: string, changed_by?: string[] }
- `POST https://api.mcp.ai/api/modem/get/topic/people` — Get every unique person who participated in one topic, including source identities, company, profile, VIP state, and contribution count.
  - body: { topic_id: string }
- `POST https://api.mcp.ai/api/modem/identify/external/records` — Upsert links from external platform records to Modem people and companies in batches of 50. Modem matches platform identities before natural keys, can create records only from the documented creation 
  - body: { idempotency_key?: string, identifications: object[] }
- `POST https://api.mcp.ai/api/modem/list/channels` — List organization channels with connection state and message counts, optionally filtered by source, name, or channel IDs.
  - body: { limit?: integer, cursor?: string, search?: string, channel_ids?: string[], source_name?: string, connected_only?: boolean }
- `POST https://api.mcp.ai/api/modem/list/companies` — List companies with person and message aggregates, optionally searching and sorting the result. Returns one page and an opaque continuation cursor.
  - body: { limit?: integer, cursor?: string, search?: string, sort_by?: string, sort_order?: string }
- `POST https://api.mcp.ai/api/modem/list/groups` — List message groups for exactly one company or one person, returning compact message content and topic context one page at a time.
  - body: { limit?: integer, cursor?: string, person_id?: string, company_id?: string }
- `POST https://api.mcp.ai/api/modem/list/people` — List people with aggregated message statistics, optionally filtering by search text, ecosystem tags, or company and sorting the result. Returns one page and an opaque continuation cursor.
  - body: { limit?: integer, cursor?: string, search?: string, sort_by?: string, company_id?: string, sort_order?: string, ecosystem_tags?: string[] }
- `POST https://api.mcp.ai/api/modem/list/topics` — List or search topics by keywords or semantic meaning with organization, participant, source, status, date, and classification filters, one page at a time. Semantic search takes precedence when both s
  - body: { view?: string, limit?: integer, cursor?: string, search?: string, sort_by?: string, sources?: string[], date_end?: string, categories?: string[], date_start?: string, person_ids?: string[], priorities?: string[], sort_order?: string, company_ids?: string[], issue_types?: string[], product_ids?: string[], team_response?: string[], min_similarity?: number, exclude_sources?: string[], ticket_statuses?: string[], embedding_search?: string, lifecycle_states?: string[], exclude_categories?: string[], exclude_person_ids?: string[], exclude_priorities?: string[], exclude_company_ids?: string[], exclude_issue_types?: string[], exclude_product_ids?: string[], exclude_ticket_statuses?: string[] }
- `POST https://api.mcp.ai/api/modem/merge/companies` — Irreversibly merge one or more source companies into one surviving target. All domains, person associations, and Slack workspaces move to the target, and source records cannot be restored by this API.
  - body: { idempotency_key?: string, target_company_id: string, source_company_ids: string[], confirm_irreversible: boolean }
- `POST https://api.mcp.ai/api/modem/merge/people` — Irreversibly merge one or more source people into one surviving target. All identities, emails, and company associations move to the target, and source records cannot be restored by this API. Requires
  - body: { idempotency_key?: string, target_person_id: string, source_person_ids: string[], confirm_irreversible: boolean }
- `POST https://api.mcp.ai/api/modem/merge/topics` — Irreversibly merge 1 to 50 source topics into one surviving target. Modem archives and marks every source as merged, then copies their group and event associations to the target; this API cannot undo 
  - body: { idempotency_key?: string, target_topic_id: string, source_topic_ids: string[], confirm_irreversible: boolean }
- `POST https://api.mcp.ai/api/modem/update/companies` — Update one to 50 companies in one batch. Omitted fields remain unchanged, explicit null values clear nullable fields, and each item reports success independently.
  - body: { companies: object[], idempotency_key?: string }
- `POST https://api.mcp.ai/api/modem/update/people` — Update one to 50 people in one batch. Omitted fields remain unchanged, explicit null values clear nullable fields, and each item reports success independently.
  - body: { people: object[], idempotency_key?: string }
- `POST https://api.mcp.ai/api/modem/update/topic` — Update one topic's priority, lifecycle, issue type, complete keyword list, or archive state. Omitted fields remain unchanged; issue_type=null clears the classification.
  - body: { archived?: boolean, keywords?: string[], priority?: string, topic_id: string, issue_type?: string, archived_reason?: string, idempotency_key?: string, lifecycle_state?: string }
- `POST https://api.mcp.ai/api/modem/update/topics` — Set priority or archive state for one to 100 topics at once. Provide at least one change, use archived=false to unarchive, and provide an archive reason only with archived=true.
  - body: { archived?: boolean, priority?: string, topic_ids: string[], archived_reason?: string, idempotency_key?: string }

## Example prompts
- "What can I do in Modem?"
- "Show me a summary of my Modem account"

## More
- Page: https://mcp.ai/modem
- Agent spec (llms.txt): https://mcp.ai/modem/llms.txt
- Postman collection: https://mcp.ai/modem/postman.json