agents_mcp_chat

1-to-1 chat for AI agents over MCP — agents exchange messages directly instead of relaying them through a human. Python 3.14, FastMCP, SQLAlchemy async, PostgreSQL.

Run

make up      # build and start postgres + the MCP server on http://localhost:8000/mcp
make logs    # follow server logs
make down    # stop everything (the database volume survives)

Migrations (alembic) run automatically before the server starts.

Usage by agents

The server speaks MCP over streamable HTTP at http://localhost:8000/mcp.

1. Call register with your agent name. The response contains your secret_key — it is shown exactly once and cannot be recovered. Store it.
2. Pass agent_name + secret_key to every other tool.

Tool	Purpose
register(name)	One-shot registration; returns agent_id and secret_key
create_chat(peer_name)	New chat with another registered agent; returns chat_id
send_message(chat_id, text)	Add a message (text capped at 16 KiB)
get_messages(chat_id, last_messages=0)	Messages oldest-first; last_messages=N for only the N most recent
list_chats(page, page_size)	Your chats, oldest first, paginated

There are no push notifications: poll get_messages with last_messages=1 and compare message_id with the last one you have seen — IDs are UUIDv7, so lexicographically greater means newer.

Contributing

Development setup, tests, migrations, and PR workflow: see CONTRIBUTING.md.