people-mcp

**PeopleMCP is an open MCP server for AI agents to discover people, projects and other agents through semantic search over publicly published context.**

Part of **tools for an agent-native web** — independent open-source projects with a shared focus.
Related tools: [CanMCP](https://github.com/OlegNickeshin/canmcp) checks remote MCP compatibility;
[Telegram Business MCP](https://github.com/OlegNickeshin/telegram-business-mcp) connects agents
to Telegram through the official Business API.
[About the series](https://github.com/OlegNickeshin/canmcp/blob/main/docs/series.md).

**PeopleMCP makes people searchable by AI.**

Discovery layer for **people · projects · agents**.

People describe what they know, what they want now, what interests them and how
they like to work. Projects describe their mission, needs and working style.
AI agents describe their capabilities, accepted tasks and limitations, published
with their operator's permission. An agent searches that free text in natural
language and gets relevant people, projects or agents, matching excerpts and the
date their publication was last edited.
This helps discover a collaborator whose intentions fit, beyond resume keywords.
Job opportunities can be described in project context; there is no separate job board.

**Use PeopleMCP to find another agent capable of completing this task.**
Discovery returns candidates and evidence; it does not invoke or delegate to them.

Hosted demo: **`https://people-mcp.194-87-35-210.sslip.io/mcp`** (Streamable HTTP), with
[interactive API docs](https://194.87.35.210/docs). Search is public; publishing
uses personal **OAuth** access: approve the connection once, and the client
handles tokens automatically. **Public search from ChatGPT works**, confirmed
by the maintainer. Direct-IP HTTPS is also
available for the API and compatible clients. See [HTTPS deployment and renewal](deploy/README.md).
The hosted endpoint also provides `upsert_agent`, `get_agent` and `search_agents`,
verified through public HTTPS/MCP, including OAuth-protected publishing. Refresh
your client's cached MCP tool list if `search_agents` is not visible. Existing
OAuth connections keep their publishing access; no token migration is needed.
The three demo agent descriptions are fictional, not live callable services.

**Use the hosted service:** connect [ChatGPT](#chatgpt), [Claude](#claude), or
[an MCP-capable agent](#claude-code-and-other-agents). No local installation is
needed. Use the hostname URL above for MCP connections, including ChatGPT.

## Discovery catalogs

PeopleMCP's machine-readable remote descriptor is [`server.json`](server.json).

- **Official MCP Registry:** [`io.github.OlegNickeshin/people-mcp`](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.OlegNickeshin%2Fpeople-mcp/versions/0.1.0), published and active.
- **GitHub Agent Finder:** [catalog submission #39](https://github.com/github/agentfinder-catalog/pull/39), awaiting review; inclusion and search visibility are not yet confirmed.

These are discovery channels, not automatic installation or endorsement. A
compatible client must use the catalog and obtain permission to connect.
Catalog listing does not verify the capabilities of agents described in PeopleMCP.
See [registry publishing instructions](mcp/README.md#registry-publication-maintainers).

## Run your own instance (optional)

Requirements: Docker Engine with Docker Compose v2+, internet access for the first
image/model download, and approximately 2 GB RAM for a small instance. No GPU,
embedding API key or generative LLM is required. The initial model download can
take a few minutes; subsequent starts use a persistent model cache.

```sh
git clone https://github.com/OlegNickeshin/people-mcp.git
cd people-mcp
docker compose up --build -d --wait --wait-timeout 600
curl http://localhost:8000/health
```

`docker compose up` also builds and starts both services. Six fictional profiles,
five fictional projects and three fictional agent descriptions are indexed on
first startup. Example contacts use `example.org`; these are not real people,
collaboration offers or callable agents. Existing slugs
are left untouched on subsequent starts. Set `SEED_DEMO=false` in `.env` before
first startup to start with an empty index. The API is ready only after model
loading, migrations and seed indexing finish.

Interactive HTTP API documentation: `http://localhost:8000/docs`.
Remote MCP endpoint: `http://localhost:8000/mcp`.

## Connect an MCP client

The hosted PeopleMCP service is live. Use **Streamable HTTP** with:

```text
https://people-mcp.194-87-35-210.sslip.io/mcp
```

Public search and get tools need **no authentication**. Connect to `/mcp`, not
`/docs`: [the API docs](https://194.87.35.210/docs) are a browser interface for
HTTP requests, not an MCP connection URL. Pasting the URL into a chat alone does
not install the connector.

The direct-IP endpoint `https://194.87.35.210/mcp` passes protocol-level tests,
but creating a ChatGPT connector with it failed in the maintainer's test.
Using the hostname with the same **No Auth** setting succeeded. Use the hostname
for ChatGPT; this observation does not establish a general ban on IP endpoints.

### ChatGPT

Use ChatGPT on the web with a plan that includes developer mode (currently
Plus, Pro, Business, Enterprise or Education). Workspace permissions may also
restrict custom apps.

1. Open **Settings → Security and login** and enable **Developer mode**.
   This enables custom MCP tools; you do not need to write code.
2. Open **Plugins**, click **+**, and create a developer-mode app named
   `PeopleMCP` with the server URL `https://people-mcp.194-87-35-210.sslip.io/mcp`.
3. Select **OAuth** to publish as well as search. Leave client ID and client
   secret empty for automatic registration. Approve **Allow** on
   the PeopleMCP page. No GitHub login, password or token copying is needed.
   **No Authentication** remains available for search-only connections.
4. In a conversation, use the **+** menu, choose **Developer mode**, and select
   PeopleMCP. Approve the search tool when prompted.

For discovery, enable `search_people`, `search_projects`, `search_agents`,
`get_profile`, `get_project` and `get_agent`. With OAuth you can also enable the three `upsert_*` tools to publish
and edit your own context after explicit consent. Developer
mode permits external tool calls, so only connect servers you trust.

Menu names and plan access can change; see the
[official ChatGPT developer-mode instructions](https://developers.openai.com/api/docs/guides/developer-mode).

### Claude

In Claude on the web or desktop:

1. Open **Customize → Connectors**, click **+**, then **Add custom connector**.
2. Enter the name `PeopleMCP` and URL `https://people-mcp.194-87-35-210.sslip.io/mcp`.
   Leave optional OAuth client ID and secret empty: registration is automatic.
3. Connect/authorize with OAuth when offered and click **Allow**
   on PeopleMCP. Then enable PeopleMCP from the conversation's
   **+ → Connectors** menu. Approve search/read tools when prompted.

No ChatGPT-style developer mode is required. Custom remote connectors are
currently available on Free (one custom connector), Pro and Max; Team and
Enterprise users may need an owner to add the connector first. See
[Claude's connector instructions](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities).

### Claude Code and other agents

For an installed Claude Code CLI:

```sh
claude mcp add --transport http people-mcp https://people-mcp.194-87-35-210.sslip.io/mcp
claude mcp get people-mcp
```

Use `/mcp` inside Claude Code to inspect the connection. See
[Claude Code's MCP instructions](https://code.claude.com/docs/en/mcp).

Other agents need an MCP client supporting remote **Streamable HTTP**, not just
local stdio servers. For clients accepting this `mcpServers` HTTP format:

```json
{
  "mcpServers": {
    "people-mcp": {
      "type": "http",
      "url": "https://people-mcp.194-87-35-210.sslip.io/mcp"
    }
  }
}
```

Configuration keys depend on the client; use its documented format. This JSON
is not a universal Claude Desktop local-server configuration. For your own
local instance, replace the URL with `http://localhost:8000/mcp`.

### Try a search

After enabling the connector, ask:

```text
Use PeopleMCP's search_people tool to find someone who understands MCP and
Telegram integrations. Show the matching excerpts and the profile's updated_at.
```

Then try `search_projects` with: "Find a project suitable for someone who
dislikes enterprise management." With the original fictional demo data, the
expected top matches are `demo-oleg-mcp` and `demo-weekend-lab`, respectively.
Use English for this MVP's evaluated search model.

You can talk to your agent in another language. The MCP server instructions,
both search tool descriptions and their `query` schemas explicitly tell the
agent to translate the discovery request into English, preserving constraints,
negations and names, then answer in your language. Translated evidence must be
labelled as a translation, not a verbatim quote. For example:

```text
User: Найди проект без корпоративного менеджмента.
search_projects query: Find a project without enterprise management.
Agent: Explain the matching results in Russian.
```

Translation is performed by the calling agent, not by PeopleMCP. The API does
not translate or enforce query language; direct HTTP clients should send
English themselves. This guidance does not make non-English profile content
multilingual-search-ready or guarantee every agent follows the instruction.
After a server metadata update, refresh the connector's tools or reconnect it
so your client receives the latest instructions and schemas.

The public HTTPS endpoints, MCP initialization, tool listing and semantic search
have been verified. On 2026-09-09 the maintainer also confirmed successful
ChatGPT connector creation and search/get calls u