Skip to main content
Before diving into advanced configuration, it helps to understand the key ideas behind peeps. This page explains what MCP is, how peeps models your data, how authentication works, and how the different transport options compare. You don’t need to read this before getting started, but it will give you a clearer mental model as your usage grows.

​
The MCP Protocol

Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools and data sources in a structured, secure way. Instead of relying on ad-hoc plugins or custom integrations, MCP defines a common interface: a server exposes tools, and an MCP client (your AI assistant) calls those tools during a conversation. peeps implements an MCP server that exposes your people and contact data as a set of callable tools. When your AI assistant needs to look someone up, it calls the relevant peeps tool, receives structured data back, and incorporates it into its response — all without you leaving the conversation.
You don’t need to know the MCP spec to use peeps. Your AI client handles the protocol automatically once you’ve added peeps to its configuration.

​
People and Contacts

A person record in peeps represents an individual. Each person record can include:
  • Name — full name, first name, last name
  • Role and title — job title, department
  • Email addresses — one or more associated email addresses
  • Phone numbers — direct, mobile, or work numbers
  • Organization — the company or team the person is linked to
  • Custom fields — any additional metadata your workspace has defined
When your AI calls search_people or get_person, it receives a structured version of this record that it can reason about, summarize, or display.

​
Organizations

An organization record represents a company, team, or other entity. Organization records typically contain:
  • Name — the organization’s display name
  • Domain — the primary web domain (for example, acme.com)
  • Industry and size — sector classification and headcount range
  • Associated people — the contacts linked to this organization
Use search_organizations or get_organization to retrieve organization data, and list_contacts to see all people associated with a given org.

​
API Keys

Every request from the peeps MCP server to your workspace is authenticated using your API key. You set this key as the PEEPS_API_KEY environment variable in your MCP client configuration. Key properties to know:
  • Workspace-scoped — a key grants access to the specific peeps workspace it was created in. It cannot read data from other workspaces.
  • Revocable — you can revoke a key at any time from Settings → API Keys in the peeps dashboard without affecting other keys.
  • One key per client — we recommend creating a separate key for each MCP client (for example, one for Claude Desktop and one for Cursor) so you can revoke individual access without disrupting other tools.
Treat your API key like a password. Never commit it to source control or share it in plaintext. Use environment variables or a secrets manager to inject it at runtime.

​
Transports

The peeps MCP server supports two transport modes, which control how your AI client communicates with it.

​
stdio (local process)

In stdio mode, your MCP client launches the peeps server as a local subprocess and communicates with it over standard input/output. This is the default mode when you use npx @peeps-ai/mcp in your client config.
  • Best for: Claude Desktop, Cursor, and other desktop AI clients
  • How it works: the client starts the server process automatically; no separate server process needs to be running
  • Network: all communication stays on your machine; only outbound API calls go to peeps

​
HTTP/SSE (remote server)

In HTTP/SSE mode, your MCP client connects to the hosted peeps MCP server over HTTP using Server-Sent Events. The remote server URL is:
  • Best for: web-based AI clients, server-side agents, or environments where running a local subprocess isn’t practical
  • How it works: your client sends requests to the remote endpoint; authentication is still handled via PEEPS_API_KEY
  • Network: traffic goes over HTTPS to mcp.peeps.ai
Both transports expose exactly the same tools and return the same data. Choose the transport that best fits your client’s capabilities and your infrastructure.