Personal MCP server

Русская версия →

A public door where other people's agents read your context and leave you a message. No authentication, and none coming — a read layer that anyone can read is the whole point of a door.

This repo is two things at once. It is a reference: the same code runs postnikov.ai/mcp, answering strangers' agents since August 2026. And it is a template: nothing personal lives in the code, all of it lives in context/, which never enters git. Fork it, drop your own files in, run it — you have a server built to the HCP shape.

Why you'd want one at all — the idea, the live example and what not to build: humancontext.pro.

Five minutes

# 1. Your own copy — "Use this template" on GitHub, or locally:
git clone https://github.com/postnikov/hcp-server.git my-mcp
cd my-mcp && rm -rf .git && git init
npm install

# 2. Your personal layer
cp -r context.example context
$EDITOR context/who.md          # one file is enough to start
$EDITOR context/config.json     # your name, your domain, your caps

# 3. Check it here
npm test
npm start                       # http://localhost:3000/mcp

# 4. Point an agent at it
claude mcp add --transport http me http://localhost:3000/mcp

You don't have to write context/ by hand. The prompt prompts/generate-my-hcp.md in hcp-protocol drafts these files from material you already published — your CV, your posts, project READMEs, talk transcripts — and asks you questions only where the material ran out. Details in context.example/README.md.

Related MCP server: ohmyself

Three tiers: read, ask, knock

The default file set plus ask gives you seven tools, and add a file and you get an eighth. The names don't matter much; the split into three tiers does.

Access is uniform — every tier is open to every agent, with no key and no account. What separates the tiers is what each one costs you and how far it reaches: reading is free and touches nothing, ask spends your money against a budget you set, leave_message is the only path that puts something in front of a human. Everything an agent can reach is something you published on purpose; the layer you keep private is the one you never put in context/.

The server serves what you have

Tools are declared by file presence. No speaking.md, no get_speaking in tools/list — an agent never gets an empty answer from a tool you don't have. Drop in context/reading.md and get_reading appears. No code to touch.

The floor is one file. who.md and nothing else gives you a working server with two tools (get_profile, leave_message). Zero files and the server refuses to start and tells you why: an empty server is worse than no server.

Every call is written to data/journal.jsonl. That log is the instrument — it's how you find out whether anyone's agent actually comes knocking, and what they came to ask.

Your personal layer

context/                  ← yours, never enters git (.gitignore)
  config.json             name, domain, caps, description overrides
  *.md                    context files; a YAML header names the tool
  deploy.env              VPS address and domain — read only by deploy.sh
context.example/          ← the same thing as a template, committed
.env                      ← secrets, on the server; sample in .env.example

A context file may carry a header. It never reaches the agent:

---
tool: get_speaking
title: Speaking
for_agent: >
  What is inside and when it's worth calling. The agent reads this BEFORE
  it calls the tool.
---
# Speaking — Your Name

No header, and the convention from config.json → context.groups applies, then get_<filename>. No description, and an honest one-liner is generated instead of an invented one.

Everything the server says about you comes out of context/: there is not one personal word in src/. A test checks that, so it's a fact and not a promise.

config.json

The file is optional — without it the server still runs, it just talks about "the owner of this server". Full annotated version: context.example/_config.md.

Environment

All optional: with no variables at all the server serves files and takes a message. Commented sample in .env.example.

Secrets travel by environment only. They are not in the code, not in the config files, and not in git.

Limits and money

The daily ask ceilings are money-safety. Per-IP limits are not enough, because IP addresses are free for an agent and your API key is not. Hit either ceiling and the tool refuses without touching the API, and lists the free file tools instead. Resets at 00:00 UTC. Numbers live in context/config.json → ask.

Discovery

With discovery.enabled the server serves two files itself:

• /.well-known/mcp/server-card.json — the MCP registry schema (2025-09-29): reverse-DNS name, description under 100 characters, remotes[].type: streamable-http;

• /llms.txt — the same truth for an agent that reads text instead of JSON.

Both are assembled from your config and the real tool list, so there is nothing there to promise a capability you don't have. If your site already serves those files on the same domain, set SERVE_DISCOVERY=0. Two truths are worse than one.

Protocol: two eras, one endpoint

Built on SDK v2 (@modelcontextprotocol/server + @modelcontextprotocol/node). createMcpHandler serves both protocol eras on the same /mcp, from a single server factory:

• modern — 2026-07-28: no initialize; version and client ride in a per-request envelope (_meta), method and tool name are mirrored in the Mcp-Method / Mcp-Name headers (SEP-2243), and server/discover returns the overview. The response is JSON.

• legacy — 2025-era: the ordinary initialize, version negotiated from the client's request (the SDK's ceiling is 2025-11-25). The response is an SSE frame, not JSON — that's what the stateless path looks like in SDK v2. It is not a change of contract: a 200 only ever went to a client that declared Accept: text/event-stream.

Use a current SDK when you fork this. Modern clients do not negotiate their way down to legacy-era servers on their own, and an old server is a door today's agents can't open.

Deploy to your own VPS

cp context.example/deploy.env context/deploy.env   # server, domain, names
$EDITOR context/deploy.env
./deploy.sh

deploy.sh runs the tests, previews what would be deleted on production (a gate in front of --delete), mirrors the working tree, loads context/deploy.env into the environment and rebuilds the container, then smoke-tests MCP_PUBLIC_URL. .env and data/ never cross the border: secrets and the journal live on production only.

docker-compose.yml assumes traefik — domain, router priority and certresolver all come from deploy.env. The router priority must be higher than that of the site on the same domain, or requests to /mcp go to the site and the agent gets an HTML 404 instead of JSON-RPC.

No traefik? Drop the labels block, publish the port and put anything that speaks TLS in front.

Check a running server

# the tool list
curl -s localhost:3000/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq -r '.result.tools[].name'

# a file tool
curl -s localhost:3000/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_profile","arguments":{}}}' \
  | jq -r '.result.content[0].text'

A hand-written curl in the modern era, with no Mcp-Method / Mcp-Name, gets -32020 back. That is the correct answer, not a breakage. The real check is an official MCP client.

Rules worth keeping

• Public facts only. Everything in context/ goes to any agent, with no authorization. Nothing about family, health, finances or deal sizes.

• No prices at all — "pricing on request, use leave_message". Otherwise your rate card ends up in someone else's cache and outlives every correction you make.

• Context is read at process start. Edit a file, restart the server.

• No tool executes the content of its arguments: the question in ask is sent declared as data, and a leave_message goes to a file and to a notification with no markup. Don't break that.

• Read every version with your own eyes before it ships. An agent that assembles your pack from your notes will happily carry something private across.

Layout

context.example/  template for the personal layer (context/ is yours, not in git)
src/config.js     config: defaults, context/config.json, env
src/context.js    your files → sections and the tool list
src/mcp.js        the protocol: tools, schemas, journal, mounting /mcp
src/lib.js        state on disk, budget cap, validation, Anthropic + notifications
src/discovery.js  server-card.json and llms.txt from the config
src/server.js     express, client IP behind a proxy, rate-limit buckets, startup
test.js           node:test on fixtures, everything outbound mocked
data/             journal.jsonl, inbox.jsonl, budget.json (not in git)

Two dependencies: express and the MCP SDK. No ORM, no database, no SMTP client — mail goes out over plain fetch. Keep it that way.

License

MIT — take it, change it, run it, sell services on top of it. Attribution belongs in the code (the copyright line in LICENSE), not on your site. What's in your context/ is yours either way: the code never touches it.