feat(tools): add per-server parallel_tool_calls to the MCP client

MCPServer gains ParallelToolCalls (default false). The client's
per-server callMu is now nil for a server that opted in, so CallTool
stops serializing that server's calls and the caller's own concurrency
decides; every other server keeps exactly one tools/call in flight.

The flag is threaded from config through the provider constructor -
the only place MCPServer configs become Client instances - into
NewClient, in both the daemon and the agent worker.
This commit is contained in:
sam committed 2026-09-22 01:57:58 +10:00
1 parent 2de6fe7ed9
commit 22ed337c20
11 files changed
+325 -35

No files matched your search

+5
View File
@@ -200,12 +200,17 @@ class = "ollama"
# a Playwright/Puppeteer-based server fetching a browser binary from a CDN
# via its postinstall script) -- consult that package's own env vars for
# those.
# Most MCP servers are single-threaded and get one tools/call at a time.
# parallel_tool_calls = true (default false) drops that serialization for
# this server only, for a server whose own implementation handles
# concurrent requests. It never affects another configured server.
# [[tools.mcp_servers]]
# name = "desktop-commander"
# transport = "stdio"
# command = "npx"
# args = ["-y", "@wonderwhy-er/desktop-commander@0.2.46", "--no-onboarding"]
# work_dir = "/path/to/workspace"
# parallel_tool_calls = false
# Workspace code-search index. Paths default under work_dir when unset.
[indexing]
+1 -1
View File
@@ -89,7 +89,7 @@ func buildMCPProvider(server config.MCPServer) (toolprovider.Engine, string, err
if err != nil {
return nil, transportType, err
}
return mcptoolprovider.New(name, transport), transportType, nil
return mcptoolprovider.New(name, transport, server.ParallelToolCalls), transportType, nil
}
func mcpTransportForServer(
+3 -3
View File
@@ -221,7 +221,7 @@ func configuredMCPProvider(server config.MCPServer, workDir string) (toolprovide
Dir: server.WorkDir,
Env: npmCacheServerEnv(command, workDir),
})
return mcptoolprovider.New(name, transport), nil
return mcptoolprovider.New(name, transport, server.ParallelToolCalls), nil
case "http", "streamablehttp":
url := strings.TrimSpace(server.URL)
@@ -232,7 +232,7 @@ func configuredMCPProvider(server config.MCPServer, workDir string) (toolprovide
Endpoint: url,
Headers: server.Headers,
})
return mcptoolprovider.New(name, transport), nil
return mcptoolprovider.New(name, transport, server.ParallelToolCalls), nil
case "sse":
sseEndpoint := strings.TrimSpace(server.SSEEndpoint)
@@ -244,7 +244,7 @@ func configuredMCPProvider(server config.MCPServer, workDir string) (toolprovide
MessageEndpoint: strings.TrimSpace(server.MessageEndpoint),
Headers: server.Headers,
})
return mcptoolprovider.New(name, transport), nil
return mcptoolprovider.New(name, transport, server.ParallelToolCalls), nil
default:
return nil, fmt.Errorf("MCP transport %q is not supported", transportType)
+7
View File
@@ -340,6 +340,13 @@ type MCPServer struct {
// MessageEndpoint is the POST URL for client→server messages. When
// empty, the client discovers it from the server's "endpoint" SSE event.
MessageEndpoint string `toml:"message_endpoint" yaml:"message_endpoint" json:"message_endpoint,omitempty"`
// ParallelToolCalls lifts the client's serialization of tools/call for
// this server only, letting concurrent callers overlap. Default false:
// one call in flight at a time, because most MCP servers are
// single-threaded processes that do not handle concurrent requests
// safely. Set it only for a server whose implementation does.
ParallelToolCalls bool `toml:"parallel_tool_calls" yaml:"parallel_tool_calls" json:"parallel_tool_calls"`
}
// ToolPolicy holds tool execution limits.
+41
View File
@@ -76,6 +76,47 @@ work_dir = "/workspace"
}
}
func TestMCPServerParallelToolCallsDecodesFromTOML(t *testing.T) {
tests := []struct {
name string
server string
want bool
}{
{
name: "absent key leaves the server serialized",
server: `
[[tools.mcp_servers]]
name = "desktop-commander"
command = "npx"
`,
},
{
name: "parallel_tool_calls opts the server in",
server: `
[[tools.mcp_servers]]
name = "desktop-commander"
command = "npx"
parallel_tool_calls = true
`,
want: true,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
var cfg Config
if _, err := toml.Decode(tt.server, &cfg); err != nil {
t.Fatal(err)
}
if len(cfg.Tools.MCPServers) != 1 {
t.Fatalf("MCPServers = %#v, want one server", cfg.Tools.MCPServers)
}
if got := cfg.Tools.MCPServers[0].ParallelToolCalls; got != tt.want {
t.Fatalf("ParallelToolCalls = %t, want %t", got, tt.want)
}
})
}
}
func TestChatModelCatalogDecodesFromTOML(t *testing.T) {
var cfg Config
if _, err := toml.Decode(`
+16 -6
View File
@@ -33,15 +33,23 @@ type Client struct {
nextID atomic.Int64
// callMu serializes tools/call requests to this server. Most MCP
// servers are single-threaded processes and don't expect or handle
// concurrent requests safely.
// concurrent requests safely, so serializing is the default. A server
// whose config declares it handles concurrent requests gets no callMu:
// nil means this server's calls are never held apart.
callMu *sync.Mutex
}
// NewClient builds a Client over transport. serverName identifies this
// MCP server in log/error messages; it need not match the server's own
// self-reported name.
func NewClient(transport Transport, serverName string) *Client {
return &Client{transport: transport, serverName: serverName, callMu: &sync.Mutex{}}
// self-reported name. parallelToolCalls drops the per-server serialization
// of tools/call: false (the default) keeps one call in flight at a time,
// true lets the caller's own concurrency through.
func NewClient(transport Transport, serverName string, parallelToolCalls bool) *Client {
c := &Client{transport: transport, serverName: serverName}
if !parallelToolCalls {
c.callMu = &sync.Mutex{}
}
return c
}
// InitializeResult is the server's response to initialize.
@@ -155,8 +163,10 @@ func (c *Client) ListTools(ctx context.Context) ([]ToolSchema, error) {
// reported via CallToolResult.IsError, not a Go error -- see
// [CallToolResult].
func (c *Client) CallTool(ctx context.Context, name string, arguments map[string]any) (CallToolResult, error) {
c.callMu.Lock()
defer c.callMu.Unlock()
if c.callMu != nil {
c.callMu.Lock()
defer c.callMu.Unlock()
}
params := map[string]any{"name": name, "arguments": arguments}
var result CallToolResult
+2 -2
View File
@@ -51,7 +51,7 @@ func (f *fakeSender) Notify(_ context.Context, body []byte) error {
}
func newTestClient(f *fakeSender) *Client {
return NewClient(f, "test-server")
return NewClient(f, "test-server", false)
}
func TestInitializeSendsInitializeThenInitializedNotification(t *testing.T) {
@@ -157,7 +157,7 @@ func TestListToolsFollowsPaginationCursor(t *testing.T) {
return page1, nil
}
return page2, nil
}), "test-server")
}), "test-server", false)
toolList, err := c.ListTools(context.Background())
if err != nil {
+125 -4
View File
@@ -14,6 +14,11 @@ import (
// once (parallel) or one completes before the next starts (serialized).
type blockingSender struct {
release chan struct{}
// entered receives one token per Send that starts, before that Send
// blocks on release. A test counts the tokens to learn how many calls
// the client allowed to overlap; unlike a sampled maximum, a token is
// only ever sent by a call that really reached Send.
entered chan struct{}
mu sync.Mutex
inFlight int
@@ -28,6 +33,9 @@ func (b *blockingSender) Send(_ context.Context, body []byte) ([]byte, error) {
}
b.mu.Unlock()
if b.entered != nil {
b.entered <- struct{}{}
}
<-b.release
b.mu.Lock()
@@ -47,9 +55,122 @@ func (b *blockingSender) MaxInFlight() int {
return b.maxInFlight
}
// overlapWindow bounds how long a test gives calls to reach Send. A call
// that is genuinely allowed to overlap reaches Send microseconds after its
// goroutine starts, so a call still absent after this window is being held
// back by the client, not by the scheduler.
const overlapWindow = 500 * time.Millisecond
// enteredCount reports how many of n calls reached Send within window.
func enteredCount(entered <-chan struct{}, n int, window time.Duration) int {
count := 0
for range n {
select {
case <-entered:
count++
case <-time.After(window):
return count
}
}
return count
}
// TestCallToolParallelToolCallsControlsSameServerOverlap pins the per-server
// flag: a server that has not opted in keeps one tools/call in flight, and a
// server that opted in lets its calls overlap.
func TestCallToolParallelToolCallsControlsSameServerOverlap(t *testing.T) {
tests := []struct {
name string
parallelToolCalls bool
wantInFlight int
}{
{
name: "server that has not opted in serializes tools/call",
wantInFlight: 1,
},
{
name: "opted-in server overlaps tools/call",
parallelToolCalls: true,
wantInFlight: 2,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
b := &blockingSender{entered: make(chan struct{}, 2), release: make(chan struct{})}
c := NewClient(b, "test-server", tt.parallelToolCalls)
errs := make([]error, 2)
started := make(chan struct{}, len(errs))
var wg sync.WaitGroup
for i := range errs {
wg.Go(func() {
started <- struct{}{}
_, errs[i] = c.CallTool(context.Background(), "slow", nil)
})
}
// Both callers are inside CallTool before either is measured, so
// the count is what the client allowed, not the scheduler's.
for range errs {
<-started
}
if got := enteredCount(b.entered, len(errs), overlapWindow); got != tt.wantInFlight {
t.Fatalf("calls in flight at once = %d, want %d", got, tt.wantInFlight)
}
close(b.release)
wg.Wait()
for i, err := range errs {
if err != nil {
t.Fatalf("call %d: %v", i, err)
}
}
})
}
}
// TestParallelToolCallsIsPerServer pins the isolation half of the flag: one
// server opting in must not un-serialize another server in the same process,
// even while the opted-in server's own calls are overlapping.
func TestParallelToolCallsIsPerServer(t *testing.T) {
optedIn := &blockingSender{entered: make(chan struct{}, 2), release: make(chan struct{})}
serialized := &blockingSender{entered: make(chan struct{}, 2), release: make(chan struct{})}
parallel := NewClient(optedIn, "opted-in", true)
sequential := NewClient(serialized, "default", false)
call := func(c *Client) {
if _, err := c.CallTool(context.Background(), "slow", nil); err != nil {
t.Errorf("CallTool: %v", err)
}
}
var parallelWG sync.WaitGroup
for range 2 {
parallelWG.Go(func() { call(parallel) })
}
if got := enteredCount(optedIn.entered, 2, overlapWindow); got != 2 {
t.Fatalf("opted-in server calls in flight = %d, want 2", got)
}
// The opted-in server's calls are still open when the other server is
// measured, so a leak of its parallelism would show up here.
var sequentialWG sync.WaitGroup
for range 2 {
sequentialWG.Go(func() { call(sequential) })
}
if got := enteredCount(serialized.entered, 2, overlapWindow); got != 1 {
t.Fatalf("server that did not opt in calls in flight = %d, want 1: opting one server in must not free another server's calls", got)
}
close(optedIn.release)
close(serialized.release)
parallelWG.Wait()
sequentialWG.Wait()
}
func TestCallToolSerializesByDefault(t *testing.T) {
b := &blockingSender{release: make(chan struct{})}
c := NewClient(b, "test-server")
c := NewClient(b, "test-server", false)
const n = 5
var wg sync.WaitGroup
@@ -73,7 +194,7 @@ func TestCallToolSerializesByDefault(t *testing.T) {
func TestCallToolSerializedStillCompletesAllCalls(t *testing.T) {
b := &blockingSender{release: make(chan struct{})}
close(b.release) // never actually blocks -- just verifying correctness, not timing
c := NewClient(b, "test-server")
c := NewClient(b, "test-server", false)
const n = 10
var completed atomic.Int32
@@ -98,8 +219,8 @@ func TestCallToolSerializationDoesNotBlockDifferentClients(t *testing.T) {
b1 := &blockingSender{release: make(chan struct{})}
b2 := &blockingSender{release: make(chan struct{})}
close(b2.release) // c2's own call should complete immediately, unblocked
c1 := NewClient(b1, "server-1")
c2 := NewClient(b2, "server-2")
c1 := NewClient(b1, "server-1", false)
c2 := NewClient(b2, "server-2", false)
done := make(chan struct{})
go func() {
@@ -25,7 +25,7 @@ func TestDesktopCommanderClientCompatibility(t *testing.T) {
},
Dir: "../../..",
})
provider := New("desktop-commander", transport)
provider := New("desktop-commander", transport, false)
if err := provider.Start(ctx); err != nil {
t.Fatalf("start Desktop Commander through MCP client: %v", err)
}
+15 -6
View File
@@ -39,6 +39,12 @@ type Provider struct {
transport LifecycleTransport
client *protocol.Client
// parallelToolCalls is the configured server's opt-in to concurrent
// tools/call. It is handed to the client Start builds: the client is
// what serializes calls, so the flag has to reach it or the server
// stays serialized.
parallelToolCalls bool
// mediaDir is the root directory binary content blocks (images, audio,
// resource blobs) are written under, created lazily on the first
// multimodal tool result. It is removed by Stop.
@@ -48,12 +54,15 @@ type Provider struct {
mediaCallSeq atomic.Int64
}
// New creates an MCP tool provider.
func New(name string, transport LifecycleTransport) *Provider {
// New creates an MCP tool provider. parallelToolCalls mirrors the
// configured server's own flag: false (the default) has the provider's
// client serialize tools/call, true lets them overlap.
func New(name string, transport LifecycleTransport, parallelToolCalls bool) *Provider {
return &Provider{
name: strings.TrimSpace(name),
segment: sanitizeToolSegment(name),
transport: transport,
name: strings.TrimSpace(name),
segment: sanitizeToolSegment(name),
transport: transport,
parallelToolCalls: parallelToolCalls,
}
}
@@ -94,7 +103,7 @@ func (p *Provider) Start(ctx context.Context) error {
if err := p.transport.Start(ctx); err != nil {
return fmt.Errorf("start MCP server %q: %w", p.name, err)
}
client := protocol.NewClient(p.transport, p.name)
client := protocol.NewClient(p.transport, p.name, p.parallelToolCalls)
if _, err := client.Initialize(ctx); err != nil {
cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), cleanupTimeout)
stopErr := p.transport.Stop(cleanupCtx)
+109 -12
View File
@@ -8,6 +8,7 @@ import (
"strings"
"sync"
"testing"
"time"
"github.com/samcharles93/archie-core/internal/tools"
protocol "github.com/samcharles93/archie-core/internal/tools/mcp"
@@ -21,7 +22,7 @@ func TestProviderInitializesDiscoversAndCallsOriginalMCPTool(t *testing.T) {
Description: "Search repositories",
InputSchema: tools.JSONSchema{"type": "object"},
}}
provider := New("Git Hub/Prod", transport)
provider := New("Git Hub/Prod", transport, false)
manifest := provider.Manifest()
if manifest.ID != "mcp.git-hub-prod" {
@@ -71,6 +72,83 @@ func TestProviderInitializesDiscoversAndCallsOriginalMCPTool(t *testing.T) {
}
}
// callOverlapWindow bounds how long a test gives tool calls to reach the
// transport. A call allowed to overlap gets there microseconds after its
// goroutine starts, so one still absent after this window is held back by
// the client, not by the scheduler.
const callOverlapWindow = 500 * time.Millisecond
// reachedSend reports how many of n calls reached Send within window.
func reachedSend(entered <-chan struct{}, n int, window time.Duration) int {
count := 0
for range n {
select {
case <-entered:
count++
case <-time.After(window):
return count
}
}
return count
}
// TestProviderParallelToolCallsReachTheMCPClient pins the wiring half of the
// per-server flag: the choice made at construction has to reach the client
// the provider builds in Start, or a server that opted in stays serialized
// with no other symptom.
func TestProviderParallelToolCallsReachTheMCPClient(t *testing.T) {
tests := []struct {
name string
parallelToolCalls bool
wantInFlight int
}{
{
name: "provider for a server that has not opted in keeps one tool call in flight",
wantInFlight: 1,
},
{
name: "provider for an opted-in server overlaps tool calls",
parallelToolCalls: true,
wantInFlight: 2,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
transport := newFakeTransport()
transport.listed = []protocol.ToolSchema{{Name: "slow"}}
transport.callEntered = make(chan struct{}, 2)
transport.callRelease = make(chan struct{})
provider := New("slow-server", transport, tt.parallelToolCalls)
if err := provider.Start(context.Background()); err != nil {
t.Fatal(err)
}
entries, err := provider.Discover(context.Background())
if err != nil {
t.Fatal(err)
}
if len(entries) != 1 {
t.Fatalf("Discover() count = %d, want 1", len(entries))
}
var wg sync.WaitGroup
for range 2 {
wg.Go(func() {
if _, err := entries[0].Handler(context.Background(), nil); err != nil {
t.Errorf("handler: %v", err)
}
})
}
if got := reachedSend(transport.callEntered, 2, callOverlapWindow); got != tt.wantInFlight {
t.Fatalf("tool calls in flight at once = %d, want %d", got, tt.wantInFlight)
}
close(transport.callRelease)
wg.Wait()
})
}
}
func TestProviderSurfacesMCPToolLevelErrors(t *testing.T) {
transport := newFakeTransport()
transport.listed = []protocol.ToolSchema{{Name: "fails"}}
@@ -78,7 +156,7 @@ func TestProviderSurfacesMCPToolLevelErrors(t *testing.T) {
Content: []protocol.ContentBlock{{Type: "text", Text: "denied"}},
IsError: true,
}
provider := New("errors", transport)
provider := New("errors", transport, false)
if err := provider.Start(context.Background()); err != nil {
t.Fatal(err)
}
@@ -104,7 +182,7 @@ func TestProviderPreservesResourceTextAndMultimodalResults(t *testing.T) {
{Type: "resource", Resource: &protocol.ResourceContent{Text: " resource context"}},
{Type: "image", Data: "aW1hZ2U=", MimeType: "image/png"},
}}
provider := New("media", transport)
provider := New("media", transport, false)
if err := provider.Start(context.Background()); err != nil {
t.Fatal(err)
}
@@ -135,7 +213,7 @@ func TestProviderWritesBinaryContentToDeliverableMediaRefs(t *testing.T) {
{Type: "audio", Data: "YXVkaW8=", MimeType: "audio/wav"},
{Type: "resource", Resource: &protocol.ResourceContent{MimeType: "application/pdf", Blob: "cGRm"}},
}}
provider := New("media", transport)
provider := New("media", transport, false)
if err := provider.Start(context.Background()); err != nil {
t.Fatal(err)
}
@@ -214,7 +292,7 @@ func TestProviderStartFailureStopsTransport(t *testing.T) {
transport := newFakeTransport()
transport.startErr = tt.startErr
transport.sendErr = tt.sendErr
provider := New("failure", transport)
provider := New("failure", transport, false)
if err := provider.Start(context.Background()); err == nil {
t.Fatal("Start() succeeded")
}
@@ -237,7 +315,7 @@ func TestProviderRejectsInvalidConfiguration(t *testing.T) {
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
provider := New(tt.server, tt.transport)
provider := New(tt.server, tt.transport, false)
if err := provider.Start(context.Background()); err == nil {
t.Fatal("Start() succeeded")
}
@@ -246,7 +324,7 @@ func TestProviderRejectsInvalidConfiguration(t *testing.T) {
}
func TestProviderSatisfiesEngine(t *testing.T) {
var _ toolprovider.Engine = New("compile", newFakeTransport())
var _ toolprovider.Engine = New("compile", newFakeTransport(), false)
}
// Compile-time checks: HTTP and SSE transports satisfy LifecycleTransport.
@@ -293,6 +371,13 @@ type fakeTransport struct {
notifyMethods []string
calledName string
calledArgs map[string]any
// callEntered receives one token per tools/call that reaches Send, and
// the call then blocks until callRelease is closed. Set both before
// Start to hold tool calls open and observe how many the client let
// overlap.
callEntered chan struct{}
callRelease chan struct{}
}
func newFakeTransport() *fakeTransport {
@@ -332,11 +417,6 @@ func (t *fakeTransport) State() protocol.TransportState {
}
func (t *fakeTransport) Send(_ context.Context, body []byte) ([]byte, error) {
t.mu.Lock()
defer t.mu.Unlock()
if t.sendErr != nil {
return nil, t.sendErr
}
var request struct {
ID json.RawMessage `json:"id"`
Method string `json:"method"`
@@ -345,6 +425,23 @@ func (t *fakeTransport) Send(_ context.Context, body []byte) ([]byte, error) {
if err := json.Unmarshal(body, &request); err != nil {
return nil, err
}
// Outside the lock: holding it here would serialize the calls this hook
// exists to observe, making a parallel client look serialized.
if request.Method == "tools/call" {
if t.callEntered != nil {
t.callEntered <- struct{}{}
}
if t.callRelease != nil {
<-t.callRelease
}
}
t.mu.Lock()
defer t.mu.Unlock()
if t.sendErr != nil {
return nil, t.sendErr
}
var result any
switch request.Method {
case "initialize":