agentflow

a multi-agent assistant template with mcp (model context protocol) support. compose specialist agents, let a claude orchestrator route between them, and plug in any mcp server to extend its toolbox.

stack

next.js 14 (app router), typescript, tailwind. vercel ai sdk (ai, @ai-sdk/anthropic) for streaming and tool-use. claude-sonnet-4-6 as the orchestrator, claude-haiku-4-5-20251001 for sub-agents. @modelcontextprotocol/sdk for the mcp client plus a small example stdio server. zod for tool schemas.

architecture

                                +-----------------+
   browser  <--  SSE stream  -- |  /api/agent     |
                                |  (Next.js API)  |
                                +--------+--------+
                                         |
                                  orchestrate()
                                         |
                +------------------------+------------------------+
                |                        |                        |
        +-------v-------+        +-------v-------+        +-------v-------+
        | local tools   |        | sub-agents    |        | MCP tools     |
        | (zod)         |        | researcher    |        | (stdio)       |
        |               |        | coder         |        | example, ...  |
        +---------------+        +---------------+        +-------+-------+
                                                                  |
                                                          spawned subprocess
                                                          (mcp-servers/*.ts)

the orchestrator calls everything as a tool: local zod tools, sub-agent delegation, and tools discovered at request time from configured mcp servers.

quick start

cp .env.example .env.local
# add ANTHROPIC_API_KEY=sk-ant-...
npm install
npm run dev

open http://localhost:3000.

connecting an mcp server

the bundled example server lives at mcp-servers/example-tools.ts and is spawned on every chat request. to wire in your own, set MCP_SERVERS to a json array:

MCP_SERVERS='[
  { "name": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
  { "name": "example", "command": "tsx", "args": ["mcp-servers/example-tools.ts"] }
]'

each remote tool is exposed to the orchestrator as <serverName>__<toolName> (e.g. example__get_weather).

sub-agents

sub-agents are plain async functions of shape (prompt: string) => Promise<string>. the orchestrator invokes them via delegate_research and delegate_coding tools. to add one:

1. drop a file in lib/agents/
2. export an async function
3. register a delegation tool in lib/agents/orchestrator.ts

env

name	required	notes
ANTHROPIC_API_KEY	yes	server-side claude key
MCP_SERVERS	no	json array of {name, command, args?}

scripts

script	what
npm run dev	next.js dev server
npm run build	production build
npm run start	start built app
npm run mcp:example	run the example mcp server standalone (debugging)

license

mit.