agent-network

⚠️ This project is currently under active development. Features may be incomplete, APIs may change, and things may break. Use at your own risk.

Let your Claude Code talk to your friend's Claude Code. Ask questions about their codebase or delegate coding tasks to their agent — all from your terminal.

Your Claude Code  -->  MCP Server  -->  HTTP  -->  Friend's A2A Server  -->  Claude Agent SDK
     (ask_agent)       (stdio)         (a2a)       (Express)                (query())

---

Step-by-Step Setup (You + One Friend)

Both you and your friend follow these steps on your own machines.

Step 1: Clone and install

git clone git@github.com:sharifli4/agent-network.git
cd agent-network
npm install

Step 2: Generate your bearer token

This is your password — it protects your agent from unauthorized access.

openssl rand -hex 32

Save the output. You'll need it in the next step AND you'll share it with your friend.

Step 3: Create your .env file

cp .env.example .env

Edit .env with your values:

PORT=3000
BEARER_TOKEN=<paste your generated token here>
AGENT_NAME=kenan
AGENT_DESCRIPTION=Backend API agent (NestJS)
WORKING_DIRECTORY=/home/kenan/repositories/my-project
ANTHROPIC_API_KEY=sk-ant-your-key-here

What each variable does:

Variable	What it is	Example
PORT	Port your server runs on	3000
BEARER_TOKEN	Your token — share this with your friend	a3f1b9c8e2d4...
AGENT_NAME	Your name	kenan
AGENT_DESCRIPTION	What your codebase is about	Backend API agent (NestJS)
WORKING_DIRECTORY	The project folder your agent can access	/home/kenan/repos/my-project
ANTHROPIC_API_KEY	Your Anthropic API key	sk-ant-...

Step 4: Exchange info with your friend

Send your friend:

• Your IP address (run ip addr | grep 'inet ' | grep -v 127.0.0.1)
• Your port (default 3000)
• Your bearer token

Get from your friend:

• Their IP address
• Their port
• Their bearer token

Step 5: Create agents.config.json

This file tells your MCP tools where your friend's agent lives.

cp agents.config.example.json agents.config.json
chmod 600 agents.config.json

Edit it with your friend's info:

{
  "agents": [
    {
      "name": "shahriyar",
      "url": "http://192.168.1.50:3000",
      "description": "Frontend agent (React Native)",
      "bearerToken": "token-your-friend-gave-you"
    }
  ]
}

You can add multiple friends — just add more entries to the agents array.

Step 6: Start your A2A server

npm run dev:server

You should see:

A2A server listening on port 3000
Agent card: http://localhost:3000/.well-known/agent.json
A2A endpoint: http://localhost:3000/a2a

Verify it works:

curl http://localhost:3000/health
# {"status":"ok"}

Step 7: Add MCP server to Claude Code

Edit ~/.claude/settings.json and add:

{
  "mcpServers": {
    "agent-network": {
      "command": "npx",
      "args": ["tsx", "/home/you/agent-network/src/mcp/index.ts"],
      "env": {
        "AGENT_NETWORK_CONFIG": "/home/you/agent-network/agents.config.json"
      }
    }
  }
}

Replace /home/you/agent-network with your actual path.

Restart Claude Code for the MCP server to load.

Step 8: Test the connection

Before using Claude Code, verify you can reach your friend's server:

# Check their agent card
curl http://<friends-ip>:3000/.well-known/agent.json

# Send a test RPC call
curl -X POST http://<friends-ip>:3000/a2a \
  -H "Authorization: Bearer <token-they-gave-you>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tasks/get","params":{"id":"test"}}'

If you get a JSON response (even an error like "Task not found"), the connection works.

---

Usage

Once everything is set up, you have 3 tools available in Claude Code:

1. List your network

"Who can I talk to?"

Just ask Claude Code to list agents, or it will call:

list_agents

Returns all agents from your agents.config.json.

2. Ask a question (read-only)

"Ask my friend about their codebase"

ask shahriyar what authentication library the frontend uses

Claude Code calls ask_agent under the hood. The remote agent can only read files — it cannot modify anything. Use this for:

• "What framework does the frontend use?"
• "How does their auth flow work?"
• "What API endpoints does their app call?"
• "What's the structure of their project?"

3. Delegate a task (read + write)

"Tell my friend's agent to do something"

delegate to shahriyar: add a loading spinner to the login screen

Claude Code calls delegate_task under the hood. The remote agent can read and write files. Use this for:

• "Add error handling to the API client"
• "Create a new component for the settings page"
• "Fix the bug in the checkout flow"
• "Update the API response type to match the new backend schema"

---

Networking

Both machines must be able to reach each other over HTTP. Options:

Situation	Solution
Same WiFi / LAN	Use local IP addresses (192.168.x.x) — works out of the box
Different networks	Use Tailscale or WireGuard for a private tunnel
Quick test over internet	Use ngrok: ngrok http 3000 gives a public URL
Have a server	SSH tunnel: ssh -R 3000:localhost:3000 your-server

---

How It Works

A2A Server (Express) — you host this on your machine. When a friend's agent sends a request, it:

1. Authenticates the bearer token
2. Creates a task
3. Runs the Claude Agent SDK against your WORKING_DIRECTORY
4. Returns the result

MCP Server (stdio) — runs inside your Claude Code. Provides the 3 tools above. When you use a tool, it sends an HTTP request to your friend's A2A server.

Security:

• ask_agent = read-only (tools: Read, Glob, Grep, Bash)
• delegate_task = full access (adds: Edit, Write)
• All requests require a valid bearer token
• agents.config.json contains tokens — keep it private (chmod 600)

---

A2A Protocol

The server implements a subset of the A2A protocol:

Endpoint	Description
GET /.well-known/agent.json	Agent card (name, description, capabilities)
GET /health	Health check
POST /a2a	JSON-RPC 2.0 — message/send and tasks/get

Scripts

Command	Description
npm run dev:server	Start A2A server (development, with hot reload)
npm run dev:mcp	Start MCP server (development)
npm run build	Compile TypeScript to dist/
npm run start:server	Start compiled A2A server
npm run start:mcp	Start compiled MCP server