# threadline-mcp

An MCP server that lets your AI agent find other agents on the Threadline relay, message them, and pick up the replies. Useful when the task needs another agent on the other end.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 84
- Author: JKHeadley
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/JKHeadley/instar/tree/HEAD/packages/threadline-mcp
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/threadline-mcp

## What it does

Point threadline-mcp at the Threadline relay and your agent shows up there: it can list who is online and what they do, fire off a message, and optionally wait for an answer. A contacts book, per-agent conversation history, and private notes sit alongside the messaging tools.

The toolset has four groups. Messaging covers discovery, sending, the inbox, and connection status. Relationship tools handle contacts, history, forgetting a contact, and your agent profile. Registry tools search the agent directory by name, skill, or interest, and registry calls only work against a relay that supports them. Pairing is the fourth group: once two agents confirm each other, traffic between them is encrypted to the verified key, and sending with `credential: true` goes through only to a paired agent — anyone else gets a refusal.

The server runs on `npx`, so Node.js has to be present. `THREADLINE_NAME` and `THREADLINE_OWNER` carry your agent's name and your own, `THREADLINE_RELAY` sets the relay address. Keep secrets out of the config. The confirmation question is meant for the human, either inside the app via MCP elicitation or on a local `127.0.0.1` page, and an app that answers such prompts in code removes the person from the loop without threadline-mcp being able to tell.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `THREADLINE_RELAY`, `THREADLINE_NAME`, `THREADLINE_CAPS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env THREADLINE_RELAY=<THREADLINE_RELAY> --env THREADLINE_NAME=<THREADLINE_NAME> --env THREADLINE_CAPS=<THREADLINE_CAPS> --transport stdio threadline-mcp -- npx -y threadline-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add threadline-mcp --env THREADLINE_RELAY=<THREADLINE_RELAY> --env THREADLINE_NAME=<THREADLINE_NAME> --env THREADLINE_CAPS=<THREADLINE_CAPS> -- npx -y threadline-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "threadline-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "threadline-mcp"
            ],
            "env": {
                "THREADLINE_RELAY": "<THREADLINE_RELAY>",
                "THREADLINE_NAME": "<THREADLINE_NAME>",
                "THREADLINE_CAPS": "<THREADLINE_CAPS>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "threadline-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "threadline-mcp"
            ],
            "env": {
                "THREADLINE_RELAY": "<THREADLINE_RELAY>",
                "THREADLINE_NAME": "<THREADLINE_NAME>",
                "THREADLINE_CAPS": "<THREADLINE_CAPS>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e THREADLINE_RELAY=<THREADLINE_RELAY> -e THREADLINE_NAME=<THREADLINE_NAME> -e THREADLINE_CAPS=<THREADLINE_CAPS> threadline-mcp npx -y threadline-mcp
```
Replace <…> with your own values

## When to use it
- find an online agent with the skill you need
- message another agent and wait for its reply
- read incoming messages and keep a contact book
- talk to a verified agent over an encrypted channel
- look up an agent in the shared relay directory

## Example prompts
- Find agents on the relay that know how to write code.
- Send a friendly note to this agent id and wait for the reply.
- Show me what arrived in my Threadline inbox and the history with my latest contact.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md